<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.8">
<title>picocli - a mighty tiny command line interface</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<style>
/* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */
/* Uncomment @import statement below to use as custom stylesheet */
/*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/
article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block}
audio,canvas,video{display:inline-block}
audio:not([controls]){display:none;height:0}
script{display:none!important}
html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}
a{background:transparent}
a:focus{outline:thin dotted}
a:active,a:hover{outline:0}
h1{font-size:2em;margin:.67em 0}
abbr[title]{border-bottom:1px dotted}
b,strong{font-weight:bold}
dfn{font-style:italic}
hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}
mark{background:#ff0;color:#000}
code,kbd,pre,samp{font-family:monospace;font-size:1em}
pre{white-space:pre-wrap}
q{quotes:"\201C" "\201D" "\2018" "\2019"}
small{font-size:80%}
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
sup{top:-.5em}
sub{bottom:-.25em}
img{border:0}
svg:not(:root){overflow:hidden}
figure{margin:0}
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
legend{border:0;padding:0}
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
button,input{line-height:normal}
button,select{text-transform:none}
button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer}
button[disabled],html input[disabled]{cursor:default}
input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0}
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
textarea{overflow:auto;vertical-align:top}
table{border-collapse:collapse;border-spacing:0}
*,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}
html,body{font-size:100%}
body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
a:hover{cursor:pointer}
img,object,embed{max-width:100%;height:auto}
object,embed{height:100%}
img{-ms-interpolation-mode:bicubic}
.left{float:left!important}
.right{float:right!important}
.text-left{text-align:left!important}
.text-right{text-align:right!important}
.text-center{text-align:center!important}
.text-justify{text-align:justify!important}
.hide{display:none}
img,object,svg{display:inline-block;vertical-align:middle}
textarea{height:auto;min-height:50px}
select{width:100%}
.center{margin-left:auto;margin-right:auto}
.stretch{width:100%}
.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr}
a{color:#2156a5;text-decoration:underline;line-height:inherit}
a:hover,a:focus{color:#1d4b8f}
a img{border:none}
p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
p aside{font-size:.875em;line-height:1.35;font-style:italic}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
h1{font-size:2.125em}
h2{font-size:1.6875em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
h4,h5{font-size:1.125em}
h6{font-size:1em}
hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}
em,i{font-style:italic;line-height:inherit}
strong,b{font-weight:bold;line-height:inherit}
small{font-size:60%;line-height:inherit}
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
ul,ol{margin-left:1.5em}
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}
ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
ul.square{list-style-type:square}
ul.circle{list-style-type:circle}
ul.disc{list-style-type:disc}
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
dl dt{margin-bottom:.3125em;font-weight:bold}
dl dd{margin-bottom:1.25em}
abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}
abbr{text-transform:none}
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}
blockquote cite::before{content:"\2014 \0020"}
blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
h1{font-size:2.75em}
h2{font-size:2.3125em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
h4{font-size:1.4375em}}
table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}
table thead,table tfoot{background:#f7f8f7}
table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
table tr.even,table tr.alt,table tr:nth-of-type(even){background:#f8f8f7}
table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
.clearfix::after,.float-group::after{clear:both}
*:not(pre)>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background-color:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word}
*:not(pre)>code.nobreak{word-wrap:normal}
*:not(pre)>code.nowrap{white-space:nowrap}
pre,pre>code{line-height:1.45;color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;text-rendering:optimizeSpeed}
em em{font-style:normal}
strong strong{font-weight:400}
.keyseq{color:rgba(51,51,51,.8)}
kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background-color:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
.keyseq kbd:first-child{margin-left:0}
.keyseq kbd:last-child{margin-right:0}
.menuseq,.menuref{color:#000}
.menuseq b:not(.caret),.menuref{font-weight:inherit}
.menuseq{word-spacing:-.02em}
.menuseq b.caret{font-size:1.25em;line-height:.8}
.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
b.button::before{content:"[";padding:0 3px 0 2px}
b.button::after{content:"]";padding:0 2px 0 3px}
p a>code:hover{color:rgba(0,0,0,.9)}
#header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
#header::after,#content::after,#footnotes::after,#footer::after{clear:both}
#content{margin-top:1.25em}
#content::before{content:none}
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap}
#header .details span:first-child{margin-left:-.125em}
#header .details span.email a{color:rgba(0,0,0,.85)}
#header .details br{display:none}
#header .details br+span::before{content:"\00a0\2013\00a0"}
#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
#header .details br+span#revremark::before{content:"\00a0|\00a0"}
#header #revnumber{text-transform:capitalize}
#header #revnumber::after{content:"\00a0"}
#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
#toc>ul{margin-left:.125em}
#toc ul.sectlevel0>li>a{font-style:italic}
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
#toc li{line-height:1.3334;margin-top:.3334em}
#toc a{text-decoration:none}
#toc a:active{text-decoration:underline}
#toctitle{color:#7a2518;font-size:1.2em}
@media screen and (min-width:768px){#toctitle{font-size:1.375em}
body.toc2{padding-left:15em;padding-right:0}
#toc.toc2{margin-top:0!important;background-color:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
#toc.toc2 ul ul{margin-left:0;padding-left:1em}
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
body.toc2.toc-right{padding-left:0;padding-right:15em}
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
#toc.toc2{width:20em}
#toc.toc2 #toctitle{font-size:1.375em}
#toc.toc2>ul{font-size:.95em}
#toc.toc2 ul ul{padding-left:1.25em}
body.toc2.toc-right{padding-left:0;padding-right:20em}}
#content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
#content #toc>:first-child{margin-top:0}
#content #toc>:last-child{margin-bottom:0}
#footer{max-width:100%;background-color:rgba(0,0,0,.8);padding:1.25em}
#footer-text{color:rgba(255,255,255,.8);line-height:1.44}
#content{margin-bottom:.625em}
.sect1{padding-bottom:.625em}
@media screen and (min-width:768px){#content{margin-bottom:1.25em}
.sect1{padding-bottom:1.25em}}
.sect1:last-child{padding-bottom:0}
.sect1+.sect1{border-top:1px solid #e7e7e9}
#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
.paragraph.lead>p,#preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit}
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
.admonitionblock>table td.icon{text-align:center;width:80px}
.admonitionblock>table td.icon img{max-width:none}
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)}
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
.exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px}
.exampleblock>.content>:first-child{margin-top:0}
.exampleblock>.content>:last-child{margin-bottom:0}
.sidebarblock{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
.sidebarblock>:first-child{margin-top:0}
.sidebarblock>:last-child{margin-bottom:0}
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
.literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class="highlight"],.listingblock pre[class^="highlight "],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#f7f7f8}
.sidebarblock .literalblock pre,.sidebarblock .listingblock pre:not(.highlight),.sidebarblock .listingblock pre[class="highlight"],.sidebarblock .listingblock pre[class^="highlight "],.sidebarblock .listingblock pre.CodeRay,.sidebarblock .listingblock pre.prettyprint{background:#f2f1f1}
.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;overflow-x:auto;padding:1em;font-size:.8125em}
@media screen and (min-width:768px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:.90625em}}
@media screen and (min-width:1280px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:1em}}
.literalblock pre.nowrap,.literalblock pre.nowrap pre,.listingblock pre.nowrap,.listingblock pre.nowrap pre{white-space:pre;word-wrap:normal}
.literalblock.output pre{color:#f7f7f8;background-color:rgba(0,0,0,.9)}
.listingblock pre.highlightjs{padding:0}
.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}
.listingblock pre.prettyprint{border-width:0}
.listingblock>.content{position:relative}
.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:#999}
.listingblock:hover code[data-lang]::before{display:block}
.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:#999}
.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
table.pyhltable{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.pyhltable td{vertical-align:top;padding-top:0;padding-bottom:0;line-height:1.45}
table.pyhltable td.code{padding-left:.75em;padding-right:0}
pre.pygments .lineno,table.pyhltable td:not(.code){color:#999;padding-left:0;padding-right:.5em;border-right:1px solid #dddddf}
pre.pygments .lineno{display:inline-block;margin-right:.25em}
table.pyhltable .linenodiv{background:none!important;padding-right:0!important}
.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
.quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em}
.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
.quoteblock blockquote{margin:0;padding:0;border:0}
.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
.verseblock{margin:0 1em 1.25em}
.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
.verseblock pre strong{font-weight:400}
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
.quoteblock .attribution br,.verseblock .attribution br{display:none}
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
.quoteblock.abstract{margin:0 1em 1.25em;display:block}
.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
.quoteblock.excerpt,.quoteblock .quoteblock{margin:0 0 1.25em;padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0}
table.tableblock{max-width:100%;border-collapse:separate}
p.tableblock:last-child{margin-bottom:0}
td.tableblock>.content{margin-bottom:-1.25em}
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0}
table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0}
table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0}
table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px}
table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0}
table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0}
table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0}
table.frame-all{border-width:1px}
table.frame-sides{border-width:0 1px}
table.frame-topbot,table.frame-ends{border-width:1px 0}
table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd){background:#f8f8f7}
table.stripes-none tr,table.stripes-odd tr:nth-of-type(even){background:none}
th.halign-left,td.halign-left{text-align:left}
th.halign-right,td.halign-right{text-align:right}
th.halign-center,td.halign-center{text-align:center}
th.valign-top,td.valign-top{vertical-align:top}
th.valign-bottom,td.valign-bottom{vertical-align:bottom}
th.valign-middle,td.valign-middle{vertical-align:middle}
table thead th,table tfoot th{font-weight:bold}
tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
p.tableblock>code:only-child{background:none;padding:0}
p.tableblock{font-size:1em}
td>div.verse{white-space:pre}
ol{margin-left:1.75em}
ul li ol{margin-left:1.5em}
dl dd{margin-left:1.125em}
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
ul.unstyled,ol.unstyled{margin-left:0}
ul.checklist{margin-left:.625em}
ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em}
ul.inline{display:-ms-flexbox;display:-webkit-box;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
ul.inline>li{margin-left:1.25em}
.unstyled dl dt{font-weight:400;font-style:normal}
ol.arabic{list-style-type:decimal}
ol.decimal{list-style-type:decimal-leading-zero}
ol.loweralpha{list-style-type:lower-alpha}
ol.upperalpha{list-style-type:upper-alpha}
ol.lowerroman{list-style-type:lower-roman}
ol.upperroman{list-style-type:upper-roman}
ol.lowergreek{list-style-type:lower-greek}
.hdlist>table,.colist>table{border:0;background:none}
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
td.hdlist1{font-weight:bold;padding-bottom:1.25em}
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
.colist td:not([class]):first-child img{max-width:none}
.colist td:not([class]):last-child{padding:.25em 0}
.thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd}
.imageblock.left{margin:.25em .625em 1.25em 0}
.imageblock.right{margin:.25em 0 1.25em .625em}
.imageblock>.title{margin-bottom:0}
.imageblock.thumb,.imageblock.th{border-width:6px}
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
.image.left{margin-right:.625em}
.image.right{margin-left:.625em}
a.image{text-decoration:none;display:inline-block}
a.image object{pointer-events:none}
sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
sup.footnote a,sup.footnoteref a{text-decoration:none}
sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
#footnotes .footnote:last-of-type{margin-bottom:0}
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}
.gist .file-data>table td.line-data{width:99%}
div.unbreakable{page-break-inside:avoid}
.big{font-size:larger}
.small{font-size:smaller}
.underline{text-decoration:underline}
.overline{text-decoration:overline}
.line-through{text-decoration:line-through}
.aqua{color:#00bfbf}
.aqua-background{background-color:#00fafa}
.black{color:#000}
.black-background{background-color:#000}
.blue{color:#0000bf}
.blue-background{background-color:#0000fa}
.fuchsia{color:#bf00bf}
.fuchsia-background{background-color:#fa00fa}
.gray{color:#606060}
.gray-background{background-color:#7d7d7d}
.green{color:#006000}
.green-background{background-color:#007d00}
.lime{color:#00bf00}
.lime-background{background-color:#00fa00}
.maroon{color:#600000}
.maroon-background{background-color:#7d0000}
.navy{color:#000060}
.navy-background{background-color:#00007d}
.olive{color:#606000}
.olive-background{background-color:#7d7d00}
.purple{color:#600060}
.purple-background{background-color:#7d007d}
.red{color:#bf0000}
.red-background{background-color:#fa0000}
.silver{color:#909090}
.silver-background{background-color:#bcbcbc}
.teal{color:#006060}
.teal-background{background-color:#007d7d}
.white{color:#bfbfbf}
.white-background{background-color:#fafafa}
.yellow{color:#bfbf00}
.yellow-background{background-color:#fafa00}
span.icon>.fa{cursor:default}
a span.icon>.fa{cursor:inherit}
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
.conum[data-value]{display:inline-block;color:#fff!important;background-color:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
.conum[data-value] *{color:#fff!important}
.conum[data-value]+b{display:none}
.conum[data-value]::after{content:attr(data-value)}
pre .conum[data-value]{position:relative;top:-.125em}
b.conum *{color:inherit!important}
.conum:not([data-value]):empty{display:none}
dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
h1,h2,p,td.content,span.alt{letter-spacing:-.01em}
p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
p,blockquote,dt,td.content,span.alt{font-size:1.0625rem}
p{margin-bottom:1.25rem}
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
.exampleblock>.content{background-color:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}
.print-only{display:none!important}
@page{margin:1.25cm .75cm}
@media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}
html{font-size:80%}
a{color:inherit!important;text-decoration:underline!important}
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
abbr[title]::after{content:" (" attr(title) ")"}
pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
thead{display:table-header-group}
svg{max-width:100%}
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
#toc,.sidebarblock,.exampleblock>.content{background:none!important}
#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
body.book #header{text-align:center}
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
body.book #header .details{border:0!important;display:block;padding:0!important}
body.book #header .details span:first-child{margin-left:0!important}
body.book #header .details br{display:block}
body.book #header .details br+span::before{content:none!important}
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
.listingblock code[data-lang]::before{display:block}
#footer{padding:0 .9375em}
.hide-on-print{display:none!important}
.print-only{display:block!important}
.hide-for-print{display:none!important}
.show-for-print{display:inherit!important}}
@media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem}
.sect1{padding:0!important}
.sect1+.sect1{border:0}
#footer{background:none}
#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
</style>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<style>
/* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
/*pre.CodeRay {background-color:#f7f7f8;}*/
.CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em}
.CodeRay span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)}
.CodeRay .line-numbers strong{color:rgba(0,0,0,.4)}
table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none}
table.CodeRay td{vertical-align: top;line-height:1.45}
table.CodeRay td.line-numbers{text-align:right}
table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)}
table.CodeRay td.code{padding:0 0 0 .5em}
table.CodeRay td.code>pre{padding:0}
.CodeRay .debug{color:#fff !important;background:#000080 !important}
.CodeRay .annotation{color:#007}
.CodeRay .attribute-name{color:#000080}
.CodeRay .attribute-value{color:#700}
.CodeRay .binary{color:#509}
.CodeRay .comment{color:#998;font-style:italic}
.CodeRay .char{color:#04d}
.CodeRay .char .content{color:#04d}
.CodeRay .char .delimiter{color:#039}
.CodeRay .class{color:#458;font-weight:bold}
.CodeRay .complex{color:#a08}
.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
.CodeRay .color{color:#099}
.CodeRay .class-variable{color:#369}
.CodeRay .decorator{color:#b0b}
.CodeRay .definition{color:#099}
.CodeRay .delimiter{color:#000}
.CodeRay .doc{color:#970}
.CodeRay .doctype{color:#34b}
.CodeRay .doc-string{color:#d42}
.CodeRay .escape{color:#666}
.CodeRay .entity{color:#800}
.CodeRay .error{color:#808}
.CodeRay .exception{color:inherit}
.CodeRay .filename{color:#099}
.CodeRay .function{color:#900;font-weight:bold}
.CodeRay .global-variable{color:#008080}
.CodeRay .hex{color:#058}
.CodeRay .integer,.CodeRay .float{color:#099}
.CodeRay .include{color:#555}
.CodeRay .inline{color:#000}
.CodeRay .inline .inline{background:#ccc}
.CodeRay .inline .inline .inline{background:#bbb}
.CodeRay .inline .inline-delimiter{color:#d14}
.CodeRay .inline-delimiter{color:#d14}
.CodeRay .important{color:#555;font-weight:bold}
.CodeRay .interpreted{color:#b2b}
.CodeRay .instance-variable{color:#008080}
.CodeRay .label{color:#970}
.CodeRay .local-variable{color:#963}
.CodeRay .octal{color:#40e}
.CodeRay .predefined{color:#369}
.CodeRay .preprocessor{color:#579}
.CodeRay .pseudo-class{color:#555}
.CodeRay .directive{font-weight:bold}
.CodeRay .type{font-weight:bold}
.CodeRay .predefined-type{color:inherit}
.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
.CodeRay .key{color:#808}
.CodeRay .key .delimiter{color:#606}
.CodeRay .key .char{color:#80f}
.CodeRay .value{color:#088}
.CodeRay .regexp .delimiter{color:#808}
.CodeRay .regexp .content{color:#808}
.CodeRay .regexp .modifier{color:#808}
.CodeRay .regexp .char{color:#d14}
.CodeRay .regexp .function{color:#404;font-weight:bold}
.CodeRay .string{color:#d20}
.CodeRay .string .string .string{background:#ffd0d0}
.CodeRay .string .content{color:#d14}
.CodeRay .string .char{color:#d14}
.CodeRay .string .delimiter{color:#d14}
.CodeRay .shell{color:#d14}
.CodeRay .shell .delimiter{color:#d14}
.CodeRay .symbol{color:#990073}
.CodeRay .symbol .content{color:#a60}
.CodeRay .symbol .delimiter{color:#630}
.CodeRay .tag{color:#008080}
.CodeRay .tag-special{color:#d70}
.CodeRay .variable{color:#036}
.CodeRay .insert{background:#afa}
.CodeRay .delete{background:#faa}
.CodeRay .change{color:#aaf;background:#007}
.CodeRay .head{color:#f8f;background:#505}
.CodeRay .insert .insert{color:#080}
.CodeRay .delete .delete{color:#800}
.CodeRay .change .change{color:#66f}
.CodeRay .head .head{color:#f4f}
</style>
</head>
<body class="article toc2 toc-left">
<div id="header">
<h1>picocli - a mighty tiny command line interface</h1>
<div class="details">
<span id="revnumber">version 4.2.0,</span>
<span id="revdate">2020-02-12</span>
</div>
<div id="toc" class="toc2">
<div id="toctitle">Features</div>
<ul class="sectlevel1">
<li><a href="#_introduction">1. Introduction</a></li>
<li><a href="#_getting_started">2. Getting Started</a>
<ul class="sectlevel2">
<li><a href="#_add_as_external_dependency">2.1. Add as External Dependency</a></li>
<li><a href="#_add_as_source">2.2. Add as Source</a></li>
<li><a href="#_annotation_processor">2.3. Annotation Processor</a></li>
</ul>
</li>
<li><a href="#_options_and_parameters">3. Options and Parameters</a>
<ul class="sectlevel2">
<li><a href="#_options">3.1. Options</a></li>
<li><a href="#_interactive_password_options">3.2. Interactive (Password) Options</a></li>
<li><a href="#_short_posix_options">3.3. Short (POSIX) Options</a></li>
<li><a href="#_boolean_options">3.4. Boolean Options</a></li>
<li><a href="#_negatable_options">3.5. Negatable Options</a></li>
<li><a href="#_positional_parameters">3.6. Positional Parameters</a></li>
<li><a href="#_mixing_options_and_positional_parameters">3.7. Mixing Options and Positional Parameters</a></li>
<li><a href="#_double_dash">3.8. Double dash (<code>--</code>)</a></li>
<li><a href="#AtFiles">3.9. @-files</a></li>
</ul>
</li>
<li><a href="#_strongly_typed_everything">4. Strongly Typed Everything</a>
<ul class="sectlevel2">
<li><a href="#_built_in_types">4.1. Built-in Types</a></li>
<li><a href="#_custom_type_converters">4.2. Custom Type Converters</a></li>
<li><a href="#_handling_invalid_input">4.3. Handling Invalid Input</a></li>
<li><a href="#_option_specific_type_converters">4.4. Option-specific Type Converters</a></li>
<li><a href="#_arrays_collections_maps">4.5. Arrays, Collections, Maps</a></li>
<li><a href="#_abstract_field_types">4.6. Abstract Field Types</a></li>
<li><a href="#_enum_types">4.7. Enum Types</a></li>
</ul>
</li>
<li><a href="#_default_values">5. Default Values</a>
<ul class="sectlevel2">
<li><a href="#defaultValue-annotation">5.1. <code>defaultValue</code> Annotation</a></li>
<li><a href="#_field_values">5.2. Field Values</a></li>
<li><a href="#_default_provider">5.3. Default Provider</a></li>
<li><a href="#_propertiesdefaultprovider">5.4. PropertiesDefaultProvider</a></li>
<li><a href="#fallbackValue-annotation">5.5. <code>fallbackValue</code> Annotation</a></li>
</ul>
</li>
<li><a href="#_multiple_values">6. Multiple Values</a>
<ul class="sectlevel2">
<li><a href="#_multiple_occurrences">6.1. Multiple Occurrences</a></li>
<li><a href="#_split_regex">6.2. Split Regex</a></li>
<li><a href="#_arity">6.3. Arity</a></li>
<li><a href="#_default_arity">6.4. Default Arity</a></li>
<li><a href="#_optional_values">6.5. Optional Values</a></li>
</ul>
</li>
<li><a href="#_required_arguments">7. Required Arguments</a>
<ul class="sectlevel2">
<li><a href="#_required_options">7.1. Required Options</a></li>
<li><a href="#_required_parameters">7.2. Required Parameters</a></li>
<li><a href="#_options_with_an_optional_parameter">7.3. Options with an Optional Parameter</a></li>
</ul>
</li>
<li><a href="#_argument_groups">8. Argument Groups</a>
<ul class="sectlevel2">
<li><a href="#_mutually_exclusive_options">8.1. Mutually Exclusive Options</a></li>
<li><a href="#_mutually_dependent_options">8.2. Mutually Dependent Options</a></li>
<li><a href="#_option_sections_in_usage_help">8.3. Option Sections in Usage Help</a></li>
<li><a href="#_repeating_composite_argument_groups">8.4. Repeating Composite Argument Groups</a></li>
<li><a href="#_default_values_in_argument_groups">8.5. Default Values in Argument Groups</a></li>
<li><a href="#_positional_parameters_2">8.6. Positional Parameters</a></li>
<li><a href="#_argument_group_limitations">8.7. Argument Group Limitations</a></li>
</ul>
</li>
<li><a href="#execute">9. Executing Commands</a>
<ul class="sectlevel2">
<li><a href="#_exit_code">9.1. Exit Code</a></li>
<li><a href="#_generating_an_exit_code">9.2. Generating an Exit Code</a></li>
<li><a href="#_exception_exit_codes">9.3. Exception Exit Codes</a></li>
<li><a href="#_usage_help_exit_code_section">9.4. Usage Help Exit Code Section</a></li>
<li><a href="#_execution_configuration">9.5. Execution Configuration</a></li>
<li><a href="#_migration">9.6. Migration</a></li>
<li><a href="#_diy_command_execution">9.7. DIY Command Execution</a></li>
<li><a href="#_handling_errors">9.8. Handling Errors</a></li>
</ul>
</li>
<li><a href="#_parser_configuration">10. Parser Configuration</a>
<ul class="sectlevel2">
<li><a href="#_overwriting_single_options">10.1. Overwriting Single Options</a></li>
<li><a href="#_stop_at_positional">10.2. Stop At Positional</a></li>
<li><a href="#_unmatched_input">10.3. Unmatched Input</a></li>
<li><a href="#unmatched-annotation">10.4. <code>@Unmatched</code> annotation</a></li>
<li><a href="#_unknown_options">10.5. Unknown Options</a></li>
<li><a href="#_stop_at_unmatched">10.6. Stop At Unmatched</a></li>
<li><a href="#_toggle_boolean_flags">10.7. Toggle Boolean Flags</a></li>
<li><a href="#_posix_clustered_short_options">10.8. POSIX Clustered Short Options</a></li>
<li><a href="#_lenient_mode_incubating">10.9. Lenient Mode (Incubating)</a></li>
<li><a href="#_quoted_values">10.10. Quoted Values</a></li>
<li><a href="#_customizing_negatable_options">10.11. Customizing Negatable Options</a></li>
<li><a href="#_custom_parameter_processing">10.12. Custom Parameter Processing</a></li>
</ul>
</li>
<li><a href="#_help">11. Help</a>
<ul class="sectlevel2">
<li><a href="#_help_options">11.1. Help Options</a></li>
<li><a href="#_mixin_standard_help_options">11.2. Mixin Standard Help Options</a></li>
<li><a href="#_built_in_help_subcommand">11.3. Built-in Help Subcommand</a></li>
<li><a href="#_custom_help_subcommands">11.4. Custom Help Subcommands</a></li>
<li><a href="#_printing_help_automatically">11.5. Printing Help Automatically</a></li>
</ul>
</li>
<li><a href="#_version_help">12. Version Help</a>
<ul class="sectlevel2">
<li><a href="#_static_version_information">12.1. Static Version Information</a></li>
<li><a href="#_dynamic_version_information">12.2. Dynamic Version Information</a></li>
</ul>
</li>
<li><a href="#_usage_help">13. Usage Help</a>
<ul class="sectlevel2">
<li><a href="#_compact_example">13.1. Compact Example</a></li>
<li><a href="#_command_name">13.2. Command Name</a></li>
<li><a href="#_parameter_labels">13.3. Parameter Labels</a></li>
<li><a href="#_unsorted_option_list">13.4. Unsorted Option List</a></li>
<li><a href="#_reordering_options">13.5. Reordering Options</a></li>
<li><a href="#_abbreviated_synopsis">13.6. Abbreviated Synopsis</a></li>
<li><a href="#_custom_synopsis">13.7. Custom Synopsis</a></li>
<li><a href="#_synopsis_subcommand_label">13.8. Synopsis Subcommand Label</a></li>
<li><a href="#_header_and_footer">13.9. Header and Footer</a></li>
<li><a href="#_exit_code_list">13.10. Exit Code List</a></li>
<li><a href="#_format_specifiers">13.11. Format Specifiers</a></li>
<li><a href="#_section_headings">13.12. Section Headings</a></li>
<li><a href="#_expanded_example">13.13. Expanded Example</a></li>
<li><a href="#_option_parameter_separators">13.14. Option-Parameter Separators</a></li>
<li><a href="#_hidden_options_and_parameters">13.15. Hidden Options and Parameters</a></li>
<li><a href="#_show_at_files">13.16. Show At Files</a></li>
<li><a href="#_show_default_values">13.17. Show Default Values</a></li>
<li><a href="#_required_option_marker">13.18. Required-Option Marker</a></li>
<li><a href="#_usage_width">13.19. Usage Width</a></li>
<li><a href="#_auto_terminal_width">13.20. Auto (Terminal) Width</a></li>
<li><a href="#_long_option_column_width">13.21. Long Option Column Width</a></li>
</ul>
</li>
<li><a href="#_ansi_colors_and_styles">14. ANSI Colors and Styles</a>
<ul class="sectlevel2">
<li><a href="#_colorized_example">14.1. Colorized Example</a></li>
<li><a href="#_usage_help_with_styles_and_colors">14.2. Usage Help with Styles and Colors</a></li>
<li><a href="#_styles_and_colors_in_application_output">14.3. Styles and Colors in Application Output</a></li>
<li><a href="#_more_colors">14.4. More Colors</a></li>
<li><a href="#_configuring_fixed_elements">14.5. Configuring Fixed Elements</a></li>
<li><a href="#_supported_platforms">14.6. Supported Platforms</a></li>
<li><a href="#_forcing_ansi_onoff">14.7. Forcing ANSI On/Off</a></li>
<li><a href="#_heuristics_for_enabling_ansi">14.8. Heuristics for Enabling ANSI</a></li>
</ul>
</li>
<li><a href="#_usage_help_api">15. Usage Help API</a>
<ul class="sectlevel2">
<li><a href="#_reordering_sections">15.1. Reordering Sections</a></li>
<li><a href="#_custom_layout">15.2. Custom Layout</a></li>
</ul>
</li>
<li><a href="#_subcommands">16. Subcommands</a>
<ul class="sectlevel2">
<li><a href="#_registering_subcommands_declaratively">16.1. Registering Subcommands Declaratively</a></li>
<li><a href="#_registering_subcommands_programmatically">16.2. Registering Subcommands Programmatically</a></li>
<li><a href="#_subcommand_aliases">16.3. Subcommand Aliases</a></li>
<li><a href="#_subcommands_as_methods">16.4. Subcommands as Methods</a></li>
<li><a href="#_executing_subcommands">16.5. Executing Subcommands</a></li>
<li><a href="#_initialization_before_execution">16.6. Initialization Before Execution</a></li>
<li><a href="#_manually_parsing_subcommands">16.7. Manually Parsing Subcommands</a></li>
<li><a href="#parentcommand-annotation">16.8. <code>@ParentCommand</code> Annotation</a></li>
<li><a href="#_nested_sub_subcommands">16.9. Nested sub-Subcommands</a></li>
<li><a href="#_repeatable_subcommands">16.10. Repeatable Subcommands</a></li>
<li><a href="#_usage_help_for_subcommands">16.11. Usage Help for Subcommands</a></li>
<li><a href="#_hidden_subcommands">16.12. Hidden Subcommands</a></li>
<li><a href="#_help_subcommands">16.13. Help Subcommands</a></li>
<li><a href="#_required_subcommands">16.14. Required Subcommands</a></li>
</ul>
</li>
<li><a href="#_reuse">17. Reuse</a>
<ul class="sectlevel2">
<li><a href="#_subclassing">17.1. Subclassing</a></li>
<li><a href="#_mixins">17.2. Mixins</a></li>
<li><a href="#_use_case_sharing_options">17.3. Use Case: Sharing Options</a></li>
<li><a href="#_reuse_combinations">17.4. Reuse Combinations</a></li>
</ul>
</li>
<li><a href="#_internationalization">18. Internationalization</a>
<ul class="sectlevel2">
<li><a href="#_configuration">18.1. Configuration</a></li>
<li><a href="#_example_resource_bundle">18.2. Example Resource Bundle</a></li>
<li><a href="#_shared_resource_bundles">18.3. Shared Resource Bundles</a></li>
<li><a href="#_localizing_the_built_in_help">18.4. Localizing the Built-In Help</a></li>
<li><a href="#_localizing_default_values">18.5. Localizing Default Values</a></li>
</ul>
</li>
<li><a href="#_variable_interpolation">19. Variable Interpolation</a>
<ul class="sectlevel2">
<li><a href="#_variable_interpolation_example">19.1. Variable Interpolation Example</a></li>
<li><a href="#_predefined_variables">19.2. Predefined Variables</a></li>
<li><a href="#_custom_variables">19.3. Custom Variables</a></li>
<li><a href="#_default_values_for_custom_variables">19.4. Default Values for Custom Variables</a></li>
<li><a href="#_escaping_variables">19.5. Escaping Variables</a></li>
<li><a href="#_switching_off_variable_interpolation">19.6. Switching Off Variable Interpolation</a></li>
<li><a href="#_limitations_of_variable_interpolation">19.7. Limitations of Variable Interpolation</a></li>
</ul>
</li>
<li><a href="#_tips_tricks">20. Tips &amp; Tricks</a>
<ul class="sectlevel2">
<li><a href="#option-parameters-methods">20.1. <code>@Option</code> and <code>@Parameters</code> Methods</a></li>
<li><a href="#command-methods">20.2.  <code>@Command</code> Methods</a></li>
<li><a href="#spec-annotation">20.3.  <code>@Spec</code> Annotation</a></li>
<li><a href="#_improved_support_for_chinese_japanese_and_korean">20.4. Improved Support for Chinese, Japanese and Korean</a></li>
<li><a href="#_custom_factory">20.5. Custom Factory</a></li>
<li><a href="#_boolean_options_with_parameters">20.6. Boolean Options with Parameters</a></li>
<li><a href="#_hexadecimal_values">20.7. Hexadecimal Values</a></li>
<li><a href="#_option_parameter_separators_2">20.8. Option-Parameter Separators</a></li>
<li><a href="#_best_practices_for_command_line_interfaces">20.9. Best Practices for Command Line Interfaces</a></li>
</ul>
</li>
<li><a href="#_dependency_injection">21. Dependency Injection</a>
<ul class="sectlevel2">
<li><a href="#_guice_example">21.1. Guice Example</a></li>
<li><a href="#_spring_boot_example">21.2. Spring Boot Example</a></li>
<li><a href="#_micronaut_example">21.3. Micronaut Example</a></li>
</ul>
</li>
<li><a href="#_java_9_jpms_modules">22. Java 9 JPMS Modules</a>
<ul class="sectlevel2">
<li><a href="#_module_configuration">22.1. Module Configuration</a></li>
</ul>
</li>
<li><a href="#_osgi_bundle">23. OSGi Bundle</a></li>
<li><a href="#_tracing">24. Tracing</a></li>
<li><a href="#_tab_autocomplete">25. TAB Autocomplete</a></li>
<li><a href="#_generate_man_page_documentation">26. Generate Man Page Documentation</a></li>
<li><a href="#_testing_your_application">27. Testing Your Application</a>
<ul class="sectlevel2">
<li><a href="#_black_box_and_white_box_testing">27.1. Black Box and White Box Testing</a></li>
<li><a href="#_testing_the_output">27.2. Testing the Output</a></li>
<li><a href="#_testing_the_exit_code">27.3. Testing the Exit Code</a></li>
<li><a href="#_testing_environment_variables">27.4. Testing Environment Variables</a></li>
</ul>
</li>
<li><a href="#_packaging_your_application">28. Packaging Your Application</a>
<ul class="sectlevel2">
<li><a href="#_graalvm_native_image">28.1. GraalVM Native Image</a></li>
<li><a href="#_build_tool_plugins">28.2. Build Tool Plugins</a></li>
<li><a href="#_launch4j">28.3. launch4j</a></li>
<li><a href="#_javapackager_java_8">28.4. javapackager (Java 8)</a></li>
<li><a href="#_jlink_java_9">28.5. jlink (Java 9+)</a></li>
<li><a href="#_jpackage_early_access">28.6. jpackage (Early Access)</a></li>
<li><a href="#_jbang">28.7. jbang</a></li>
</ul>
</li>
<li><a href="#_picocli_in_other_languages">29. Picocli in Other Languages</a>
<ul class="sectlevel2">
<li><a href="#_groovy">29.1. Groovy</a></li>
<li><a href="#_kotlin">29.2. Kotlin</a></li>
<li><a href="#_scala">29.3. Scala</a></li>
</ul>
</li>
<li><a href="#_api_javadoc">30. API Javadoc</a></li>
<li><a href="#_github_project">31. GitHub Project</a></li>
<li><a href="#_issue_tracker">32. Issue Tracker</a></li>
<li><a href="#_mailing_list">33. Mailing List</a></li>
<li><a href="#_license">34. License</a></li>
<li><a href="#_releases">35. Releases</a></li>
<li><a href="#_download">36. Download</a>
<ul class="sectlevel2">
<li><a href="#_gradle_3">36.1. Gradle</a></li>
<li><a href="#_maven_3">36.2. Maven</a></li>
<li><a href="#_scala_sbt">36.3. Scala SBT</a></li>
<li><a href="#_ivy">36.4. Ivy</a></li>
<li><a href="#_source">36.5. Source</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="imageblock right">
<div class="content">
<a class="image" href="https://github.com/remkop/picocli"><img src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png" alt="Fork me on GitHub"></a>
</div>
</div>
<iframe src="https://ghbtns.com/github-btn.html?user=remkop&repo=picocli&type=star&count=true" frameborder="0" scrolling="0" width="170px" height="20px" style="float:right"></iframe>
<div class="quoteblock">
<blockquote>
Every main method deserves picocli!
</blockquote>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/logo/horizontal.png" alt="picocli the Mighty Tiny Command Line Interface" width="800"></span></p>
</div>
<div class="paragraph">
<p>The user manual for the latest release is at <a href="http://picocli.info" class="bare">http://picocli.info</a>.
For the busy and impatient: there is also a <a href="quick-guide.html">Quick Guide</a>.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_introduction">1. Introduction</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Picocli aims to be the easiest way to create rich command line applications that can run on and off the JVM.</p>
</div>
<div class="paragraph">
<p>Picocli is a one-file framework for creating Java command line applications with almost zero code.
Supports a variety of command line syntax styles including POSIX, GNU, MS-DOS and more.
Generates highly customizable usage help messages with <a href="#_ansi_colors_and_styles">ANSI colors and styles</a>.
Picocli-based applications can have <a href="autocomplete.html">command line TAB completion</a> showing available options, option parameters and subcommands, for any level of nested subcommands.
Picocli-based applications can be ahead-of-time compiled to a <span class="image"><img src="https://www.graalvm.org/resources/img/logo-colored.svg" alt="GraalVM"></span>
<a href="#_graalvm_native_image">native image</a>, with extremely fast startup time and lower memory requirements, which can be distributed as a single executable file.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/checksum-usage-help.png" alt="Screenshot of usage help with Ansi codes enabled"></span></p>
</div>
<div class="paragraph">
<p>Picocli <a href="#_generate_man_page_documentation">generates beautiful documentation</a> for your application (HTML, PDF and Unix man pages).</p>
</div>
<div class="paragraph">
<p>Another distinguishing feature of picocli is how it aims
to let users run picocli-based applications without requiring picocli as an external dependency:
all the source code lives in a single file, to encourage application authors to include it <em>in source form</em>.</p>
</div>
<div class="paragraph">
<p>How it works: annotate your class and picocli initializes it from the command line arguments,
converting the input to strongly typed values in the fields of your class.</p>
</div>
<div id="CheckSum-application" class="listingblock">
<div class="title">A full working example picocli-based command line application</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">picocli.CommandLine</span>;
<span class="keyword">import</span> <span class="include">picocli.CommandLine.Command</span>;
<span class="keyword">import</span> <span class="include">picocli.CommandLine.Option</span>;
<span class="keyword">import</span> <span class="include">picocli.CommandLine.Parameters</span>;

<span class="keyword">import</span> <span class="include">java.io.File</span>;
<span class="keyword">import</span> <span class="include">java.math.BigInteger</span>;
<span class="keyword">import</span> <span class="include">java.nio.file.Files</span>;
<span class="keyword">import</span> <span class="include">java.security.MessageDigest</span>;
<span class="keyword">import</span> <span class="include">java.util.concurrent.Callable</span>;

<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">checksum</span><span class="delimiter">&quot;</span></span>, mixinStandardHelpOptions = <span class="predefined-constant">true</span>, version = <span class="string"><span class="delimiter">&quot;</span><span class="content">checksum 4.0</span><span class="delimiter">&quot;</span></span>,
         description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Prints the checksum (MD5 by default) of a file to STDOUT.</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">CheckSum</span> <span class="directive">implements</span> <span class="predefined-type">Callable</span>&lt;<span class="predefined-type">Integer</span>&gt; {

    <span class="annotation">@Parameters</span>(index = <span class="string"><span class="delimiter">&quot;</span><span class="content">0</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">The file whose checksum to calculate.</span><span class="delimiter">&quot;</span></span>)
    <span class="directive">private</span> <span class="predefined-type">File</span> file;

    <span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-a</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--algorithm</span><span class="delimiter">&quot;</span></span>}, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">MD5, SHA-1, SHA-256, ...</span><span class="delimiter">&quot;</span></span>)
    <span class="directive">private</span> <span class="predefined-type">String</span> algorithm = <span class="string"><span class="delimiter">&quot;</span><span class="content">MD5</span><span class="delimiter">&quot;</span></span>;

    <span class="comment">// this example implements Callable, so parsing, error handling and handling user</span>
    <span class="comment">// requests for usage help or version help can be done with one line of code.</span>
    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span>... args) {
        <span class="type">int</span> exitCode = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> CheckSum()).execute(args);
        <span class="predefined-type">System</span>.exit(exitCode);
    }

    <span class="annotation">@Override</span>
    <span class="directive">public</span> <span class="predefined-type">Integer</span> call() <span class="directive">throws</span> <span class="exception">Exception</span> { <span class="comment">// your business logic goes here...</span>
        <span class="type">byte</span><span class="type">[]</span> fileContents = Files.readAllBytes(file.toPath());
        <span class="type">byte</span><span class="type">[]</span> digest = <span class="predefined-type">MessageDigest</span>.getInstance(algorithm).digest(fileContents);
        <span class="predefined-type">System</span>.out.printf(<span class="string"><span class="delimiter">&quot;</span><span class="content">%0</span><span class="delimiter">&quot;</span></span> + (digest.length*<span class="integer">2</span>) + <span class="string"><span class="delimiter">&quot;</span><span class="content">x%n</span><span class="delimiter">&quot;</span></span>, <span class="keyword">new</span> <span class="predefined-type">BigInteger</span>(<span class="integer">1</span>, digest));
        <span class="keyword">return</span> <span class="integer">0</span>;
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Implement <code>Runnable</code> or <code>Callable</code>, and your command can be <a href="#execute">executed</a> in one line of code.
The example above uses the <code>CommandLine.execute</code> method
to parse the command line, handle errors, handle requests for usage and version help, and invoke the business logic.
Applications can call <code>System.exit</code> with the returned exit code to signal success or failure to their caller.</p>
</div>
<div class="paragraph">
<p>The <a href="#_mixin_standard_help_options">mixinStandardHelpOptions</a> attribute adds <code>--help</code> and <code>--version</code> options to your application.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_getting_started">2. Getting Started</h2>
<div class="sectionbody">
<div class="paragraph">
<p>You can add picocli as an external dependency to your project, or you can include it as source.</p>
</div>
<div class="sect2">
<h3 id="_add_as_external_dependency">2.1. Add as External Dependency</h3>
<div class="paragraph">
<p>Below are examples of configuring Gradle or Maven to use picocli as an external dependency in your project.</p>
</div>
<div class="sect3">
<h4 id="_gradle">2.1.1. Gradle</h4>
<div class="listingblock">
<div class="content">
<pre>compile 'info.picocli:picocli:4.2.0'</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_maven">2.1.2. Maven</h4>
<div class="listingblock">
<div class="content">
<pre>&lt;dependency&gt;
  &lt;groupId&gt;info.picocli&lt;/groupId&gt;
  &lt;artifactId&gt;picocli&lt;/artifactId&gt;
  &lt;version&gt;4.2.0&lt;/version&gt;
&lt;/dependency&gt;</pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_add_as_source">2.2. Add as Source</h3>
<div class="paragraph">
<p>To include as source, get the source code from the <a href="https://github.com/remkop/picocli/blob/master/src/main/java/picocli/CommandLine.java">GitHub file</a>. Copy and paste it into a file called <code>CommandLine.java</code>, add it to your project, and enjoy!</p>
</div>
</div>
<div class="sect2">
<h3 id="_annotation_processor">2.3. Annotation Processor</h3>
<div class="paragraph">
<p>The <code>picocli-codegen</code> module includes an annotation processor that can build a model from the picocli annotations at compile time rather than at runtime.</p>
</div>
<div class="paragraph">
<p>Enabling this annotation processor in your project is optional, but strongly recommended. Use this if you’re interested in:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>Compile time error checking</strong>. The annotation processor shows errors for invalid annotations and attributes immediately when you compile, instead of during testing at runtime, resulting in shorter feedback cycles.</p>
</li>
<li>
<p><strong><a href="#_graalvm_native_image">GraalVM native images</a></strong>. The annotation processor generates and updates <a href="https://github.com/oracle/graal/blob/master/substratevm/CONFIGURE.md">GraalVM configuration</a> files under
<code>META-INF/native-image/picocli-generated/$project</code> during compilation, to be included in the application jar.
This includes configuration files for <a href="https://github.com/oracle/graal/blob/master/substratevm/REFLECTION.md">reflection</a>, <a href="https://github.com/oracle/graal/blob/master/substratevm/RESOURCES.md">resources</a> and <a href="https://github.com/oracle/graal/blob/master/substratevm/DYNAMIC_PROXY.md">dynamic proxies</a>.
By embedding these configuration files, your jar is instantly Graal-enabled.
In most cases no further configuration is needed when generating a native image.</p>
</li>
</ul>
</div>
<div class="sect3">
<h4 id="_processor_option_project">2.3.1. Processor option: <code>project</code></h4>
<div class="paragraph">
<p>The picocli annotation processor supports a number of <a href="https://github.com/remkop/picocli/tree/master/picocli-codegen#picocli-processor-options">options</a>, most important of which is the <code>project</code> option to control the output subdirectory: the generated files are written to <code>META-INF/native-image/picocli-generated/${project}</code>. A good convention is to use the Maven <code>${project.groupId}/${project.artifactId}</code> as the value; a unique subdirectory ensures your jar can be shaded with other jars that may also contain generated configuration files.</p>
</div>
<div class="paragraph">
<p>To configure this option, pass the <code>-Aproject=&lt;some value&gt;</code> to the javac compiler. The examples below show how to do this for Maven and Gradle.</p>
</div>
</div>
<div class="sect3">
<h4 id="_enabling_the_annotation_processor">2.3.2. Enabling the Annotation Processor</h4>
<div class="sect4">
<h5 id="_ide">IDE</h5>
<div class="paragraph">
<p><a href="https://immutables.github.io/apt.html">This page</a> shows the steps to configure Eclipse and IntelliJ IDEA to enable annotation processing.</p>
</div>
</div>
<div class="sect4">
<h5 id="_maven_2">Maven</h5>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>&lt;plugin&gt;
  &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
  &lt;artifactId&gt;maven-compiler-plugin&lt;/artifactId&gt;
  &lt;!-- annotationProcessorPaths requires maven-compiler-plugin version 3.5 or higher --&gt;
  &lt;version&gt;${maven-compiler-plugin-version}&lt;/version&gt;
  &lt;configuration&gt;
    &lt;annotationProcessorPaths&gt;
      &lt;path&gt;
        &lt;groupId&gt;info.picocli&lt;/groupId&gt;
        &lt;artifactId&gt;picocli-codegen&lt;/artifactId&gt;
        &lt;version&gt;4.2.0&lt;/version&gt;
      &lt;/path&gt;
    &lt;/annotationProcessorPaths&gt;
    &lt;compilerArgs&gt;
      &lt;arg&gt;-Aproject=${project.groupId}/${project.artifactId}&lt;/arg&gt;
    &lt;/compilerArgs&gt;
  &lt;/configuration&gt;
&lt;/plugin&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>See the <a href="https://github.com/remkop/picocli/tree/master/picocli-codegen"><code>picocli-codegen</code> README</a> for more details.</p>
</div>
</div>
<div class="sect4">
<h5 id="_gradle_2">Gradle</h5>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>dependencies {
    compile 'info.picocli:picocli:4.2.0'
    annotationProcessor 'info.picocli:picocli-codegen:4.2.0'
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>compileJava {
    options.compilerArgs += ["-Aproject=${project.group}/${project.name}"]
}</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_kotlin_projects_using_gradle">Kotlin Projects Using Gradle</h5>
<div class="paragraph">
<p>Kotlin projects should add the <code>kotlin-kapt</code> plugin to enable the Kotlin Annotation processing tool (kapt),
then replace <code>annotationProcessor</code> with <code>kapt</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>apply plugin: 'kotlin-kapt' // required
dependencies {
    // ...
    kapt 'info.picocli:picocli-codegen:4.2.0'
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>And replace <code>compileJava.options.compilerArgs</code> with <code>kapt.arguments</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>kapt {
    arguments {
        arg("project", "${project.group}/${project.name}")
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>See the <a href="https://github.com/remkop/picocli/tree/master/picocli-codegen"><code>picocli-codegen</code> README</a> for more details.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_options_and_parameters">3. Options and Parameters</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Command line arguments can be separated into <em>options</em>  and <em>positional parameters</em>.
Options have a name, positional parameters are usually the values that follow the options,
but they may be mixed.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/OptionsAndParameters2.png" alt="Example command with annotated @Option and @Parameters"></span></p>
</div>
<div class="paragraph">
<p>Picocli has separate annotations for options and positional parameters.</p>
</div>
<div class="sect2">
<h3 id="_options">3.1. Options</h3>
<div class="paragraph">
<p>An option must have one or more <code>names</code>.
Picocli lets you use any option name you want.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
You may be interested in this <a href="http://catb.org/~esr/writings/taoup/html/ch10s05.html#id2948149">list of common option names</a>. Following these conventions may make your application more intuitive to use for experienced users.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The below example shows options with one or more names, options that take an option parameter, and a <a href="#_help_options">help</a> option.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">Tar</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-c</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">create a new archive</span><span class="delimiter">&quot;</span></span>)
    <span class="type">boolean</span> create;

    <span class="annotation">@Option</span>(names = { <span class="string"><span class="delimiter">&quot;</span><span class="content">-f</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--file</span><span class="delimiter">&quot;</span></span> }, paramLabel = <span class="string"><span class="delimiter">&quot;</span><span class="content">ARCHIVE</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">the archive file</span><span class="delimiter">&quot;</span></span>)
    <span class="predefined-type">File</span> archive;

    <span class="annotation">@Parameters</span>(paramLabel = <span class="string"><span class="delimiter">&quot;</span><span class="content">FILE</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">one ore more files to archive</span><span class="delimiter">&quot;</span></span>)
    <span class="predefined-type">File</span><span class="type">[]</span> files;

    <span class="annotation">@Option</span>(names = { <span class="string"><span class="delimiter">&quot;</span><span class="content">-h</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--help</span><span class="delimiter">&quot;</span></span> }, usageHelp = <span class="predefined-constant">true</span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">display a help message</span><span class="delimiter">&quot;</span></span>)
    <span class="directive">private</span> <span class="type">boolean</span> helpRequested = <span class="predefined-constant">false</span>;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Picocli matches the option names to set the field values.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">String</span><span class="type">[]</span> args = { <span class="string"><span class="delimiter">&quot;</span><span class="content">-c</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--file</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">result.tar</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">file1.txt</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">file2.txt</span><span class="delimiter">&quot;</span></span> };
Tar tar = <span class="keyword">new</span> Tar();
<span class="keyword">new</span> CommandLine(tar).parseArgs(args);

<span class="keyword">assert</span> !tar.helpRequested;
<span class="keyword">assert</span>  tar.create;
<span class="keyword">assert</span>  tar.archive.equals(<span class="keyword">new</span> <span class="predefined-type">File</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">result.tar</span><span class="delimiter">&quot;</span></span>));
<span class="keyword">assert</span>  <span class="predefined-type">Arrays</span>.equals(tar.files, <span class="keyword">new</span> <span class="predefined-type">File</span><span class="type">[]</span> {<span class="keyword">new</span> <span class="predefined-type">File</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">file1.txt</span><span class="delimiter">&quot;</span></span>), <span class="keyword">new</span> <span class="predefined-type">File</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">file2.txt</span><span class="delimiter">&quot;</span></span>)});</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_interactive_password_options">3.2. Interactive (Password) Options</h3>
<div class="paragraph">
<p>Picocli 3.5 introduced password support: for options and positional parameters marked as <code>interactive</code>, the user is prompted to enter a value on the console.
When running on Java 6 or higher, picocli will use the <a href="https://docs.oracle.com/javase/8/docs/api/java/io/Console.html#readPassword-java.lang.String-java.lang.Object&#8230;&#8203;-"><code>Console.readPassword</code></a> API so that user input is not echoed to the console.</p>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
Interactive <em>positional parameters</em> have a limitation: they must be followed by a non-interactive positional parameter.
Commands where the <em>last</em> positional parameter is <code>interactive</code> are currently not supported.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="_example">3.2.1. Example</h4>
<div class="paragraph">
<p>The example below demonstrates how an interactive option can be used to specify a password.
From picocli 3.9.6, interactive options can use type <code>char[]</code> instead of String, to allow applications to null out the array after use so that sensitive information is no longer resident in memory.</p>
</div>
<div class="paragraph">
<p>Example usage:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">Login</span> <span class="directive">implements</span> <span class="predefined-type">Callable</span>&lt;<span class="predefined-type">Integer</span>&gt; {
    <span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-u</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--user</span><span class="delimiter">&quot;</span></span>}, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">User name</span><span class="delimiter">&quot;</span></span>)
    <span class="predefined-type">String</span> user;

    <span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-p</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--password</span><span class="delimiter">&quot;</span></span>}, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Passphrase</span><span class="delimiter">&quot;</span></span>, interactive = <span class="predefined-constant">true</span>)
    <span class="type">char</span><span class="type">[]</span> password;

    <span class="directive">public</span> <span class="predefined-type">Integer</span> call() <span class="directive">throws</span> <span class="exception">Exception</span> {
        <span class="type">byte</span><span class="type">[]</span> bytes = <span class="keyword">new</span> <span class="type">byte</span>[password.length];
        <span class="keyword">for</span> (<span class="type">int</span> i = <span class="integer">0</span>; i &lt; bytes.length; i++) { bytes[i] = (<span class="type">byte</span>) password[i]; }

        <span class="predefined-type">MessageDigest</span> md = <span class="predefined-type">MessageDigest</span>.getInstance(<span class="string"><span class="delimiter">&quot;</span><span class="content">SHA-256</span><span class="delimiter">&quot;</span></span>);
        md.update(bytes);

        <span class="predefined-type">System</span>.out.printf(<span class="string"><span class="delimiter">&quot;</span><span class="content">Hi %s, your password is hashed to %s.%n</span><span class="delimiter">&quot;</span></span>, user, base64(md.digest()));

        <span class="comment">// null out the arrays when done</span>
        <span class="predefined-type">Arrays</span>.fill(bytes, (<span class="type">byte</span>) <span class="integer">0</span>);
        <span class="predefined-type">Arrays</span>.fill(password, <span class="string"><span class="delimiter">'</span><span class="content"> </span><span class="delimiter">'</span></span>);

        <span class="keyword">return</span> <span class="integer">0</span>;
    }

    <span class="directive">private</span> <span class="predefined-type">String</span> base64(<span class="type">byte</span><span class="type">[]</span> arr) { <span class="comment">/* ... */</span> }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>When this command is invoked like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">new</span> CommandLine(<span class="keyword">new</span> Login()).execute(<span class="string"><span class="delimiter">&quot;</span><span class="content">-u</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">user123</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">-p</span><span class="delimiter">&quot;</span></span>);</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then the user will be prompted to enter a value:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>Enter value for --password (Passphrase):</code></pre>
</div>
</div>
<div class="paragraph">
<p>When running on Java 6 or higher, the user input is not echoed to the console.
After the user enters a password value and presses enter, the <code>call()</code> method is invoked, which prints something like the following:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>Hi user123, your passphrase is hashed to 75K3eLr+dx6JJFuJ7LwIpEpOFmwGZZkRiB84PURz6U8=.</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_optionally_interactive">3.2.2. Optionally Interactive</h4>
<div class="paragraph">
<p>Interactive options by default cause the application to wait for input on stdin. For commands that need to be run interactively as well as in batch mode, it is useful if the option can optionally consume an argument from the command line.</p>
</div>
<div class="paragraph">
<p>The default <a href="#_arity">arity</a> for interactive options is zero, meaning that the option takes no parameters. From picocli 3.9.6, interactive options can also take a value from the command line if configured with <code>arity = "0..1"</code>.</p>
</div>
<div class="paragraph">
<p>For example, if an application has these options:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">--user</span><span class="delimiter">&quot;</span></span>)
<span class="predefined-type">String</span> user;

<span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">--password</span><span class="delimiter">&quot;</span></span>, arity = <span class="string"><span class="delimiter">&quot;</span><span class="content">0..1</span><span class="delimiter">&quot;</span></span>, interactive = <span class="predefined-constant">true</span>)
<span class="type">char</span><span class="type">[]</span> password;</code></pre>
</div>
</div>
<div class="paragraph">
<p>With the following input, the <code>password</code> field will be initialized to <code>"123"</code> without prompting the user for input:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>--password 123 --user Joe</pre>
</div>
</div>
<div class="paragraph">
<p>However, if the password is not specified, the user will be prompted to enter a value. In the following example, the password option has no parameter, so the user will be prompted to type in a value on the console:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>--password --user Joe</pre>
</div>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
<div class="title">Providing Passwords to Batch Scripts Securely</div>
<div class="paragraph">
<p>Note that specifying a password in plain text on the command line or in scripts is not secure. There are alternatives that are more secure.</p>
</div>
<div class="paragraph">
<p>One idea is to add a separate different option (that could be named <code>--password:file</code>) that takes a <code>File</code> or <code>Path</code> parameter, where the application reads the password from the specified file.
Another idea is to add a separate different option (that could be named <code>--password:env</code>) that takes an environment variable name parameter, where the application gets the password from the user’s environment variables.</p>
</div>
<div class="paragraph">
<p>A command that combines either of these with an interactive <code>--password</code> option (with the default <code>arity = "0"</code>) allows end users to provide a password without specifying it in plain text on the command line. Such a command can be executed both interactively and in batch mode.</p>
</div>
<div class="paragraph">
<p>The <a href="https://github.com/remkop/picocli/blob/master/picocli-examples"><code>picocli-examples</code></a> module has an example, coded both in <a href="https://github.com/remkop/picocli/blob/master/picocli-examples/src/main/java/picocli/examples/interactive/PasswordDemo.java">Java</a> and <a href="https://github.com/remkop/picocli/tree/master/picocli-examples/src/main/kotlin/picocli/examples/kotlin/interactive/PasswordDemo.kt">Kotlin</a>.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
<div class="title">Interactive options and shell applications with JLine 2</div>
<div class="paragraph">
<p>Interactive options do not work in conjuction with JLine 2&#8217;s <code>ConsoleReader</code>. Either implement a <a href="#_custom_parameter_processing"><code>IParameterConsumer</code></a> which uses JLine2&#8217;s <code>ConsoleReader</code> directly or use <code>picocli-shell-jline3</code>.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_short_posix_options">3.3. Short (POSIX) Options</h3>
<div class="paragraph">
<p>Picocli supports <a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_02">POSIX clustered short options</a>:
one or more single-character options without option-arguments, followed by at most one option with an option-argument, can be grouped behind one '-' delimiter.</p>
</div>
<div class="paragraph">
<p>For example, given this annotated class:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">ClusteredShortOptions</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-a</span><span class="delimiter">&quot;</span></span>) <span class="type">boolean</span> aaa;
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-b</span><span class="delimiter">&quot;</span></span>) <span class="type">boolean</span> bbb;
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-c</span><span class="delimiter">&quot;</span></span>) <span class="type">boolean</span> ccc;
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-f</span><span class="delimiter">&quot;</span></span>) <span class="predefined-type">String</span>  file;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The following command line arguments are all equivalent and parsing them will give the same result:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">&lt;command&gt; -abcfInputFile.txt
&lt;command&gt; -abcf=InputFile.txt
&lt;command&gt; -abc -f=InputFile.txt
&lt;command&gt; -ab -cf=InputFile.txt
&lt;command&gt; -a -b -c -fInputFile.txt
&lt;command&gt; -a -b -c -f InputFile.txt
&lt;command&gt; -a -b -c -f=InputFile.txt
...</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_boolean_options">3.4. Boolean Options</h3>
<div class="paragraph">
<p>Boolean options usually don&#8217;t need a parameter: it is enough to specify the option name on the command line.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">BooleanOptions</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>) <span class="type">boolean</span> x;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The value of <code>x</code> is <code>false</code> by default, and is set to <code>true</code> (the opposite of the default) if the <code>-x</code> option is specified on the command line.
If the <code>-x</code> option is specified multiple times on the command line, the value of <code>x</code> remains <code>true</code>. (Prior to picocli 4.0, the value of <code>x</code> would "toggle" (flip to its opposite) for every <code>-x</code> option on the command line. This can still be <a href="#_toggle_boolean_flags">configured</a> if required.)</p>
</div>
<div class="paragraph">
<p>This is enough in most cases, but picocli offers alternatives for applications that need to get the value from something other than the default value. When the option is specified on the command line, the annotated field (or <a href="#option-parameters-methods">method</a>) is assigned a value, as follows:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>If the parser is configured to <a href="#_toggle_boolean_flags">toggle boolean options</a>, the opposite of the <em>current value</em> is assigned. (This was the default prior to picocli 4.0.)</p>
</li>
<li>
<p>If a <a href="#fallbackValue-annotation">fallback value</a> is defined, the fallback value is assigned.</p>
</li>
<li>
<p>If the option is defined with a non-zero <a href="#_arity">arity</a>, and an option parameter was specified on the command line, this option <a href="#_boolean_options_with_parameters">parameter value is assigned</a>.</p>
</li>
<li>
<p>Otherwise, the value assigned is the logical opposite of the <em>default value</em>.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="_negatable_options">3.5. Negatable Options</h3>
<div class="paragraph">
<p>From picocli 4.0, options can be <code>negatable</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">negatable-options-demo</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">NegatableOptionsDemo</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">--verbose</span><span class="delimiter">&quot;</span></span>,           negatable = <span class="predefined-constant">true</span>) <span class="type">boolean</span> verbose;
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-XX:+PrintGCDetails</span><span class="delimiter">&quot;</span></span>, negatable = <span class="predefined-constant">true</span>) <span class="type">boolean</span> printGCDetails;
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-XX:-UseG1GC</span><span class="delimiter">&quot;</span></span>,        negatable = <span class="predefined-constant">true</span>) <span class="type">boolean</span> useG1GC = <span class="predefined-constant">true</span>;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>When an option is negatable, picocli will recognize negative aliases of the option on the command line.</p>
</div>
<div class="paragraph">
<p>The usage help for the above example looks like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: negatable-options-demo [--[no-]verbose] [-XX:(+|-)PrintGCDetails]
                              [-XX:(+|-)UseG1GC]
      --[no-]verbose     Show verbose output
      -XX:(+|-)PrintGCDetails
                         Prints GC details
      -XX:(+|-)UseG1GC   Use G1 algorithm for GC</pre>
</div>
</div>
<div class="paragraph">
<p>For *nix-style long options, aliases have the prefix <code>no-</code> to the given names, for example <code>--no-verbose</code>.
For Java JVM-style options like <code>-XX:+PrintGCDetails</code>, the <code>:+</code> is turned into <code>:-</code> and vice versa.
Short option names are not given a negative alias by default. (This is <a href="#_customizing_negatable_options">customizable</a>.)</p>
</div>
<div class="paragraph">
<p>If the negated form of the option is found, for example <code>--no-verbose</code>, the value is set to the provided default. Otherwise, with a regular call, for example <code>--verbose</code>, it is set to the opposite of the default.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
<div class="title">Negatable options that are <code>true</code> by default</div>
<div class="paragraph">
<p>When a negatable option is <code>true</code> by default, give it the negative name. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">--no-backup</span><span class="delimiter">&quot;</span></span>, negatable = <span class="predefined-constant">true</span>,
  description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Make a backup. True by default.</span><span class="delimiter">&quot;</span></span>)
<span class="type">boolean</span> backup = <span class="predefined-constant">true</span>;</code></pre>
</div>
</div>
<div class="paragraph">
<p>When end users specify <code>--no-backup</code> on the command line, the value is set to <code>false</code>.</p>
</div>
<div class="paragraph">
<p>The negated form of this option is <code>--backup</code>, and if that is specified, the default value is applied.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_positional_parameters">3.6. Positional Parameters</h3>
<div class="paragraph">
<p>Any command line arguments that are not subcommands or options (or option parameters) are interpreted as positional parameters.
Positional parameters generally follow the options but from picocli 2.0, positional parameters can be mixed with options on the command line.</p>
</div>
<div class="paragraph">
<p>Use the (zero-based) <code>index</code> attribute to specify exactly which parameters to capture.
Omitting the <code>index</code> attribute means the field captures <em>all</em> positional parameters.
Array or collection fields can capture multiple values.</p>
</div>
<div class="paragraph">
<p>The <code>index</code> attribute accepts <em>range</em> values, so an annotation like <code>@Parameters(index="2..4")</code> captures the arguments at index 2, 3 and 4. Range values can be <em>open-ended</em>. For example, <code>@Parameters(index="3..*")</code> captures all arguments from index 3 and up.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">PositionalParameters</span> {
    <span class="annotation">@Parameters</span>(hidden = <span class="predefined-constant">true</span>)  <span class="comment">// &quot;hidden&quot;: don't show this parameter in usage help message</span>
    <span class="predefined-type">List</span>&lt;<span class="predefined-type">String</span>&gt; allParameters; <span class="comment">// no &quot;index&quot; attribute: captures _all_ arguments (as Strings)</span>

    <span class="annotation">@Parameters</span>(index = <span class="string"><span class="delimiter">&quot;</span><span class="content">0</span><span class="delimiter">&quot;</span></span>)    <span class="predefined-type">InetAddress</span> host;
    <span class="annotation">@Parameters</span>(index = <span class="string"><span class="delimiter">&quot;</span><span class="content">1</span><span class="delimiter">&quot;</span></span>)    <span class="type">int</span> port;
    <span class="annotation">@Parameters</span>(index = <span class="string"><span class="delimiter">&quot;</span><span class="content">2..*</span><span class="delimiter">&quot;</span></span>) <span class="predefined-type">File</span><span class="type">[]</span> files;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Picocli initializes fields with the values at the specified index in the arguments array.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">String</span><span class="type">[]</span> args = { <span class="string"><span class="delimiter">&quot;</span><span class="content">localhost</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">12345</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">file1.txt</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">file2.txt</span><span class="delimiter">&quot;</span></span> };
PositionalParameters params = CommandLine.populateCommand(<span class="keyword">new</span> PositionalParameters(), args);

<span class="keyword">assert</span> params.host.getHostName().equals(<span class="string"><span class="delimiter">&quot;</span><span class="content">localhost</span><span class="delimiter">&quot;</span></span>);
<span class="keyword">assert</span> params.port == <span class="integer">12345</span>;
<span class="keyword">assert</span> <span class="predefined-type">Arrays</span>.equals(params.files, <span class="keyword">new</span> <span class="predefined-type">File</span><span class="type">[]</span> {<span class="keyword">new</span> <span class="predefined-type">File</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">file1.txt</span><span class="delimiter">&quot;</span></span>), <span class="keyword">new</span> <span class="predefined-type">File</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">file2.txt</span><span class="delimiter">&quot;</span></span>)});
<span class="keyword">assert</span> params.allParameters.equals(<span class="predefined-type">Arrays</span>.asList(<span class="string"><span class="delimiter">&quot;</span><span class="content">localhost</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">12345</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">file1.txt</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">file2.txt</span><span class="delimiter">&quot;</span></span>));</code></pre>
</div>
</div>
<div class="paragraph">
<p>See <a href="#_strongly_typed_everything">Strongly Typed Everything</a> for which types are supported out of the box and how to add custom types.</p>
</div>
</div>
<div class="sect2">
<h3 id="_mixing_options_and_positional_parameters">3.7. Mixing Options and Positional Parameters</h3>
<div class="paragraph">
<p>From picocli 2.0, positional parameters can be specified anywhere on the command line, they no longer need to follow the options.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">Mixed</span> {
    <span class="annotation">@Parameters</span>
    <span class="predefined-type">List</span>&lt;<span class="predefined-type">String</span>&gt; positional;

    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-o</span><span class="delimiter">&quot;</span></span>)
    <span class="predefined-type">List</span>&lt;<span class="predefined-type">String</span>&gt; options;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Any command line argument that is not an option or subcommand is interpreted as a positional parameter.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">String</span><span class="type">[]</span> args = { <span class="string"><span class="delimiter">&quot;</span><span class="content">param0</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">-o</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">AAA</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">param1</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">param2</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">-o</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">BBB</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">param3</span><span class="delimiter">&quot;</span></span> };
Mixed mixed = <span class="keyword">new</span> Mixed();
<span class="keyword">new</span> CommandLine(mixed).parseArgs(args);

<span class="keyword">assert</span> mixed.positional.equals(<span class="predefined-type">Arrays</span>.asList(<span class="string"><span class="delimiter">&quot;</span><span class="content">param0</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">param1</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">param2</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">param3</span><span class="delimiter">&quot;</span></span>);
<span class="keyword">assert</span> mixed.options.equals   (<span class="predefined-type">Arrays</span>.asList(<span class="string"><span class="delimiter">&quot;</span><span class="content">AAA</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">BBB</span><span class="delimiter">&quot;</span></span>));</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_double_dash">3.8. Double dash (<code>--</code>)</h3>
<div class="paragraph">
<p>When one of the command line arguments is just two dashes without any characters attached (<code>--</code>),
picocli interprets all following arguments as positional parameters, even arguments that match an option name.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">DoubleDashDemo</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-v</span><span class="delimiter">&quot;</span></span>)     <span class="type">boolean</span> verbose;
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-files</span><span class="delimiter">&quot;</span></span>) <span class="predefined-type">List</span>&lt;<span class="predefined-type">String</span>&gt; files;
    <span class="annotation">@Parameters</span>               <span class="predefined-type">List</span>&lt;<span class="predefined-type">String</span>&gt; params;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>--</code> end-of-options delimiter clarifies which of the arguments are positional parameters:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">String</span><span class="type">[]</span> args = { <span class="string"><span class="delimiter">&quot;</span><span class="content">-v</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">-files</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">file1</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">file2</span><span class="delimiter">&quot;</span></span> };
DoubleDashDemo demo = <span class="keyword">new</span> DoubleDashDemo();
<span class="keyword">new</span> CommandLine(demo).parseArgs(args);

<span class="keyword">assert</span> demo.verbose;
<span class="keyword">assert</span> demo.files == <span class="predefined-constant">null</span>;
<span class="keyword">assert</span> demo.params.equals(<span class="predefined-type">Arrays</span>.asList(<span class="string"><span class="delimiter">&quot;</span><span class="content">-files</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">file1</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">file2</span><span class="delimiter">&quot;</span></span>));</code></pre>
</div>
</div>
<div class="paragraph">
<p>A custom delimiter can be configured with <code>CommandLine.setEndOfOptionsDelimiter(String)</code>.</p>
</div>
</div>
<div class="sect2">
<h3 id="AtFiles">3.9. @-files</h3>
<div class="sect3">
<h4 id="_argument_files_for_long_command_lines">3.9.1. Argument Files for Long Command Lines</h4>
<div class="paragraph">
<p>Users sometimes run into system limitations on the length of a command line when creating a
command line with lots of options or with long arguments for options.</p>
</div>
<div class="paragraph">
<p>Starting from v2.1.0, picocli supports "argument files" or "@-files".
Argument files are files that themselves contain arguments to the command.
When picocli encounters an argument beginning with the character `@',
it expands the contents of that file into the argument list.</p>
</div>
<div class="paragraph">
<p>An argument file can include options and positional parameters in any combination.
The arguments within a file can be space-separated or newline-separated.
If an argument contains embedded whitespace, put the whole argument in double or single quotes.
Within quoted values, backslashes need to be escaped with another backslash.</p>
</div>
<div class="paragraph">
<p>For example, it is possible to have a path with a space,
such as <code>c:\Program Files</code> that can be specified as either <code>"c:\\Program Files"</code> or,
to avoid an escape, <code>c:\Program" "Files</code>.</p>
</div>
<div class="paragraph">
<p>Lines starting with <code>#</code> are comments and are ignored.
The comment character can be configured with <code>CommandLine.setAtFileCommentChar(Character)</code>,
and comments can be switched off by setting the comment character to <code>null</code>.</p>
</div>
<div class="paragraph">
<p>The file may itself contain additional @-file arguments; any such arguments will be processed recursively.</p>
</div>
<div class="paragraph">
<p>If the file does not exist, or cannot be read, then the argument will be treated literally, and not removed.
Multiple @-files may be specified on the command line. The specified path may be relative (to the current directory) or absolute.</p>
</div>
<div class="paragraph">
<p>For example, suppose a file with arguments exists at <code>/home/foo/args</code>, with these contents:</p>
</div>
<div class="listingblock">
<div class="content">
<pre># This line is a comment and is ignored.
ABC -option=123
'X Y Z'</pre>
</div>
</div>
<div class="paragraph">
<p>A command may be invoked with the @file argument, like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">java MyCommand @/home/foo/args</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above will be expanded to the contents of the file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">java MyCommand ABC -option=123 &quot;X Y Z&quot;</code></pre>
</div>
</div>
<div class="paragraph">
<p>@-file expansion can be switched off by calling <code>CommandLine::setExpandAtFiles</code> with <code>false</code>.
If turned on, you can still pass a real parameter with an initial '@' character by escaping it
with an additional '@' symbol, e.g. '@@somearg' will become '@somearg' and not be subject to expansion.</p>
</div>
<div class="paragraph">
<p>This feature is similar to the 'Command Line Argument File' processing supported by gcc, javadoc and javac.
The documentation for these tools shows further examples.</p>
</div>
</div>
<div class="sect3">
<h4 id="_files_usage_help">3.9.2. @-files Usage Help</h4>
<div class="paragraph">
<p>From picocli 4.2, an entry for <code>@&lt;filename&gt;</code> can be shown in the options and parameters list of the usage help message of a command with the <code>@Command(showAtFileInUsageHelp = true)</code> annotation. See <a href="#_show_at_files">Show At Files</a> for details.</p>
</div>
</div>
<div class="sect3">
<h4 id="_simplified_format">3.9.3. Simplified Format</h4>
<div class="paragraph">
<p>From picocli 3.8.1, a simpler argument file format is also supported where every line (except empty lines and comment lines)
is interpreted as a single argument. Arguments containing whitespace do not need to be quoted,
but it is not possible to have arguments with embedded newlines or to have empty string arguments without quotes.
From picocli 3.9, this simpler argument format is fully compatible with <a href="http://jcommander.org/#__syntax">JCommander</a>'s <code>@-file</code> argument file format.</p>
</div>
<div class="paragraph">
<p>You can tell picocli to use the simplified argument file format programmatically with <code>CommandLine.setUseSimplifiedAtFiles(true)</code>,
or by setting system property <code>picocli.useSimplifiedAtFiles</code> without a value or with value <code>"true"</code>
(case-insensitive). The system property is useful to allow end users control over the format.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_strongly_typed_everything">4. Strongly Typed Everything</h2>
<div class="sectionbody">
<div class="paragraph">
<p>When command line options and positional parameters are mapped to the annotated fields,
the text value is converted to the type of the annotated field.</p>
</div>
<div class="sect2">
<h3 id="_built_in_types">4.1. Built-in Types</h3>
<div class="paragraph">
<p>Out of the box, picocli can convert command line argument strings to a number of common data types.</p>
</div>
<div class="paragraph">
<p>Most of the built-in types work with Java 5, but picocli also has some default converters for Java 7 types like <code>Path</code> and Java 8 types like <code>Duration</code>, etc. These converters are loaded using reflection and are only available when running on a Java version that supports them. See the below list for details.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>any Java primitive type or their wrapper</p>
</li>
<li>
<p>any <code>enum</code></p>
</li>
<li>
<p><code>String</code>, <code>StringBuilder</code>, <code>CharSequence</code></p>
</li>
<li>
<p><code>java.math.BigDecimal</code>, <code>java.math.BigInteger</code></p>
</li>
<li>
<p><code>java.nio.Charset</code></p>
</li>
<li>
<p><code>java.io.File</code></p>
</li>
<li>
<p><code>java.net.InetAddress</code></p>
</li>
<li>
<p><code>java.util.regex.Pattern</code></p>
</li>
<li>
<p><code>java.util.Date</code> (for values in <code>"yyyy-MM-dd"</code> format)</p>
</li>
<li>
<p><code>java.net.URL</code>, <code>java.net.URI</code></p>
</li>
<li>
<p><code>java.util.UUID</code></p>
</li>
<li>
<p><code>java.lang.Class</code> (from picocli 2.2, for the fully qualified class name)</p>
</li>
<li>
<p><code>java.nio.ByteOrder</code> (from picocli 2.2, for the Strings <code>"BIG_ENDIAN"</code> or <code>"LITTLE_ENDIAN"</code>)</p>
</li>
<li>
<p><code>java.util.Currency</code> (from picocli 2.2, for the ISO 4217 code of the currency)</p>
</li>
<li>
<p><code>java.net.NetworkInterface</code> (from picocli 2.2, for the InetAddress or name of the network interface)</p>
</li>
<li>
<p><code>java.util.TimeZoneConverter</code> (from picocli 2.2, for the ID for a TimeZone)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Converters loaded using reflection:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>java.nio.file.Path</code> (from picocli 2.2, requires Java 7 or higher)</p>
</li>
<li>
<p><code>java.time</code> value objects: <code>Duration</code>, <code>Instant</code>, <code>LocalDate</code>, <code>LocalDateTime</code>, <code>LocalTime</code>, <code>MonthDay</code>, <code>OffsetDateTime</code>, <code>OffsetTime</code>, <code>Period</code>, <code>Year</code>, <code>YearMonth</code>, <code>ZonedDateTime</code>, <code>ZoneId</code>, <code>ZoneOffset</code>  (from picocli 2.2, requires Java 8 or higher, invokes the <code>parse</code> method of these classes)</p>
</li>
<li>
<p><code>java.sql.Time</code> (for values in any of the <code>"HH:mm"</code>, <code>"HH:mm:ss"</code>, <code>"HH:mm:ss.SSS"</code>, or <code>"HH:mm:ss,SSS"</code> formats)</p>
</li>
<li>
<p><code>java.sql.Timestamp</code> (from picocli 2.2, for values in the <code>"yyyy-MM-dd HH:mm:ss"</code> or <code>"yyyy-MM-dd HH:mm:ss.fffffffff"</code> formats)</p>
</li>
<li>
<p><code>java.sql.Connection</code> (from picocli 2.2, for a database url of the form <code>jdbc:subprotocol:subname</code>)</p>
</li>
<li>
<p><code>java.sql.Driver</code> (from picocli 2.2, for a database URL of the form <code>jdbc:subprotocol:subname</code>)</p>
</li>
</ul>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Sometimes loading converters with reflection is not desirable.
Use system property <code>picocli.converters.excludes</code> to specify a comma-separated list of fully qualified class names for which the converter should not be loaded.
Regular expressions are supported.
For example, invoking the program with <code>-Dpicocli.converters.excludes=java.sql.Ti.*</code> will not load type converters for <code>java.sql.Time</code> and <code>java.sql.Timestamp</code>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_custom_type_converters">4.2. Custom Type Converters</h3>
<div class="paragraph">
<p>Register a custom type converter to handle data types other than the above built-in ones.</p>
</div>
<div class="paragraph">
<p>Custom converters need to implement the <code>picocli.CommandLine.ITypeConverter</code> interface:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">ITypeConverter</span>&lt;K&gt; {
    <span class="comment">/**
     * Converts the specified command line argument value to some domain object.
     * @param value the command line argument String value
     * @return the resulting domain object
     * @throws Exception an exception detailing what went wrong during the conversion
     */</span>
    K convert(<span class="predefined-type">String</span> value) <span class="directive">throws</span> <span class="exception">Exception</span>;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Custom type converters can be registered with the <code>CommandLine.registerConverter(Class&lt;K&gt; cls, ITypeConverter&lt;K&gt; converter)</code> method. All options and positional parameters with the specified type will be converted by the specified converter.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Java 8 lambdas make it easy to register custom converters:
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">CommandLine cl = <span class="keyword">new</span> CommandLine(app)
cl.registerConverter(<span class="predefined-type">Locale</span>.class, s -&gt; <span class="keyword">new</span> <span class="predefined-type">Locale</span>.Builder().setLanguageTag(s).build());
cl.registerConverter(<span class="predefined-type">Cipher</span>.class, s -&gt; <span class="predefined-type">Cipher</span>.getInstance(s));</code></pre>
</div>
</div>
<div class="paragraph">
<p>After registering custom converters, call the <code>execute(String&#8230;&#8203;)</code> or parseArgs(String&#8230;&#8203;)` method on the <code>CommandLine</code> instance where the converters are registered. (The static <code>populateCommand</code> method cannot be used.) For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">App</span> {
    <span class="annotation">@Parameters</span> java.util.Locale locale;
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-a</span><span class="delimiter">&quot;</span></span>) javax.crypto.Cipher cipher;
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">App app = <span class="keyword">new</span> App();
CommandLine commandLine = <span class="keyword">new</span> CommandLine(app)
    .registerConverter(<span class="predefined-type">Locale</span>.class, s -&gt; <span class="keyword">new</span> <span class="predefined-type">Locale</span>.Builder().setLanguageTag(s).build())
    .registerConverter(<span class="predefined-type">Cipher</span>.class, s -&gt; <span class="predefined-type">Cipher</span>.getInstance(s));

commandLine.parseArgs(<span class="string"><span class="delimiter">&quot;</span><span class="content">-a</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">AES/CBC/NoPadding</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">en-GB</span><span class="delimiter">&quot;</span></span>);
<span class="keyword">assert</span> app.locale.toLanguageTag().equals(<span class="string"><span class="delimiter">&quot;</span><span class="content">en-GB</span><span class="delimiter">&quot;</span></span>);
<span class="keyword">assert</span> app.cipher.getAlgorithm().equals(<span class="string"><span class="delimiter">&quot;</span><span class="content">AES/CBC/NoPadding</span><span class="delimiter">&quot;</span></span>);</code></pre>
</div>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
<em>Note on subcommands:</em> the specified converter will be registered with the <code>CommandLine</code> object
and all subcommands (and nested sub-subcommands) that were added <em>before</em> the converter was registered.
Subcommands added later will not have the converter added automatically.
To ensure a custom type converter is available to all subcommands, register the type converter last, after adding subcommands.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_handling_invalid_input">4.3. Handling Invalid Input</h3>
<div class="paragraph">
<p>If the user specifies invalid input, custom type converters should throw an exception.
Any exception is fine, and will result in a message like the below being displayed to the user:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Invalid value for option '-a': cannot convert 'xxxinvalidinput' to InetSocketAddress (java.lang.IllegalArgumentException: Invalid format: must be 'host:port' but was 'xxxinvalidinput')</pre>
</div>
</div>
<div class="paragraph">
<p>The above error message is generic and is reasonable for many exceptions, but sometimes you want more control over the error message displayed to the user.
To achieve this, throw a <code>picocli.CommandLine.TypeConversionException</code> instead.
When a <code>TypeConversionException</code> is thrown, picocli will show an error message that indicates the problematic option, followed by the exception message text. The resulting output looks something like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Invalid value for option '-a': Invalid format: must be 'host:port' but was 'xxxinvalidinput'</pre>
</div>
</div>
<div class="paragraph">
<p>Below is an example custom converter that throws a <code>TypeConversionException</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">java.net.InetSocketAddress</span>;

<span class="type">class</span> <span class="class">InetSocketAddressConverter</span> <span class="directive">implements</span> ITypeConverter&lt;<span class="predefined-type">InetSocketAddress</span>&gt; {
    <span class="annotation">@Override</span>
    <span class="directive">public</span> <span class="predefined-type">InetSocketAddress</span> convert(<span class="predefined-type">String</span> value) {
        <span class="type">int</span> pos = value.lastIndexOf(<span class="string"><span class="delimiter">'</span><span class="content">:</span><span class="delimiter">'</span></span>);
        <span class="keyword">if</span> (pos &lt; <span class="integer">0</span>) {
            <span class="keyword">throw</span> <span class="keyword">new</span> TypeConversionException(
                    <span class="string"><span class="delimiter">&quot;</span><span class="content">Invalid format: must be 'host:port' but was '</span><span class="delimiter">&quot;</span></span> + value + <span class="string"><span class="delimiter">&quot;</span><span class="content">'</span><span class="delimiter">&quot;</span></span>);
        }
        <span class="predefined-type">String</span> adr = value.substring(<span class="integer">0</span>, pos);
        <span class="type">int</span> port = <span class="predefined-type">Integer</span>.parseInt(value.substring(pos + <span class="integer">1</span>));
        <span class="keyword">return</span> <span class="keyword">new</span> <span class="predefined-type">InetSocketAddress</span>(adr, port);
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>picocli-examples</code> module on GitHub has a runnable <a href="https://github.com/remkop/picocli/blob/master/picocli-examples/src/main/java/picocli/examples/typeconverter/InetSocketAddressConverterDemo.java">example</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_option_specific_type_converters">4.4. Option-specific Type Converters</h3>
<div class="paragraph">
<p>Picocli 2.2 added a <code>converter</code> attribute to the <code>@Option</code> and <code>@Parameter</code> annotations. This allows a specific option or positional parameter to use a different converter than would be used by default based on the type of the field.</p>
</div>
<div class="paragraph">
<p>For example, for a specific field you may want to use a converter that maps the constant names defined in <a href="https://docs.oracle.com/javase/9/docs/api/java/sql/Types.html"><code>java.sql.Types</code></a> to the <code>int</code> value of these constants, but any other <code>int</code> fields should not be affected by this and should continue to use the standard int converter that parses numeric values.</p>
</div>
<div class="paragraph">
<p>Example usage:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">App</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">--sqlType</span><span class="delimiter">&quot;</span></span>, converter = SqlTypeConverter.class)
    <span class="type">int</span> sqlType;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Example implementation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">SqlTypeConverter</span> <span class="directive">implements</span> ITypeConverter&lt;<span class="predefined-type">Integer</span>&gt; {
    <span class="directive">public</span> <span class="predefined-type">Integer</span> convert(<span class="predefined-type">String</span> value) <span class="directive">throws</span> <span class="exception">Exception</span> {
        <span class="keyword">switch</span> (value) {
            <span class="keyword">case</span> <span class="string"><span class="delimiter">&quot;</span><span class="content">ARRAY</span><span class="delimiter">&quot;</span></span>  : <span class="keyword">return</span> <span class="predefined-type">Types</span>.ARRAY;
            <span class="keyword">case</span> <span class="string"><span class="delimiter">&quot;</span><span class="content">BIGINT</span><span class="delimiter">&quot;</span></span> : <span class="keyword">return</span> <span class="predefined-type">Types</span>.BIGINT;
            <span class="keyword">case</span> <span class="string"><span class="delimiter">&quot;</span><span class="content">BINARY</span><span class="delimiter">&quot;</span></span> : <span class="keyword">return</span> <span class="predefined-type">Types</span>.BINARY;
            <span class="keyword">case</span> <span class="string"><span class="delimiter">&quot;</span><span class="content">BIT</span><span class="delimiter">&quot;</span></span>    : <span class="keyword">return</span> <span class="predefined-type">Types</span>.BIT;
            <span class="keyword">case</span> <span class="string"><span class="delimiter">&quot;</span><span class="content">BLOB</span><span class="delimiter">&quot;</span></span>   : <span class="keyword">return</span> <span class="predefined-type">Types</span>.BLOB;
            ...
        }
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This may also be useful for applications that need a custom type converter but want to use the static convenience methods (<code>populateCommand</code>, <code>run</code>, <code>call</code>, <code>invoke</code>). The <code>converter</code> annotation does not require a <code>CommandLine</code> instance so it can be used with the static convenience methods.</p>
</div>
<div class="paragraph">
<p>Type converters declared with the <code>converter</code> attribute need to have a public no-argument constructor to be instantiated, unless a <a href="#_custom_factory">Custom Factory</a> is installed to instantiate classes.</p>
</div>
</div>
<div class="sect2">
<h3 id="_arrays_collections_maps">4.5. Arrays, Collections, Maps</h3>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Starting from picocli 2.0, the <code>type</code> attribute is no longer necessary for <code>Collection</code> and <code>Map</code> fields:
picocli will infer the collection element type from the generic type.
(The <code>type</code> attribute still works as before, it is just optional in most cases.)
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="_arrays_and_collections">4.5.1. Arrays and Collections</h4>
<div class="paragraph">
<p>Multiple parameters can be captured together in a single array or <code>Collection</code> field.
The array or collection elements can be any type for which a <a href="#_strongly_typed_everything">converter</a> is registered.
For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">java.util.regex.Pattern</span>;
<span class="keyword">import</span> <span class="include">java.io.File</span>;

<span class="type">class</span> <span class="class">Convert</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-patterns</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">the regex patterns to use</span><span class="delimiter">&quot;</span></span>)
    <span class="predefined-type">Pattern</span><span class="type">[]</span> patterns;

    <span class="annotation">@Parameters</span>(<span class="comment">/* type = File.class, */</span> description = <span class="string"><span class="delimiter">&quot;</span><span class="content">the files to convert</span><span class="delimiter">&quot;</span></span>)
    <span class="predefined-type">List</span>&lt;<span class="predefined-type">File</span>&gt; files; <span class="comment">// picocli infers type from the generic type</span>
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">String</span><span class="type">[]</span> args = { <span class="string"><span class="delimiter">&quot;</span><span class="content">-patterns</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">a*b</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">-patterns</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">[a-e][i-u]</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">file1.txt</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">file2.txt</span><span class="delimiter">&quot;</span></span> };
Convert convert = CommandLine.populateCommand(<span class="keyword">new</span> Convert(), args);

<span class="comment">// convert.patterns now has two Pattern objects</span>
<span class="comment">// convert.files now has two File objects</span></code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
If a collection is returned from a type converter, the <em>contents</em> of the collection are added to the field or method parameter, not the collection itself.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>If the field or method parameter is <code>null</code>, picocli will instantiate it when the option or positional parameter is successfully matched.
If the <code>Collection</code> type is not a concrete class, picocli will make a best effort to instantiate it based on the field type:
<code>List &#8594; ArrayList</code>, <code>OrderedSet &#8594; TreeSet</code>, <code>Set &#8594; LinkedHashSet</code>, <code>Queue &#8594; LinkedList</code>, otherwise, <code>ArrayList</code>.</p>
</div>
<div class="paragraph">
<p>Multi-value options and positional parameters can be defined with a <code>split</code> regular expression to allow end users to specify multiple values in a single parameter.
See the <a href="#_split_regex">Split Regex</a> section for details.</p>
</div>
</div>
<div class="sect3">
<h4 id="_maps">4.5.2. Maps</h4>
<div class="paragraph">
<p>Picocli 1.0 introduced support for <code>Map</code> fields similar to Java&#8217;s system properties <code>-Dkey=value</code> or Gradle&#8217;s project properties <code>-Pmyprop=myvalue</code>.</p>
</div>
<div class="paragraph">
<p><code>Map</code> fields may have any type for their key and value
as long as a <a href="#_strongly_typed_everything">converter</a> is registered for both the key and the value type.
Key and value types are inferred from the map&#8217;s generic type parameters.
For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">java.net.InetAddress</span>;
<span class="keyword">import</span> <span class="include">java.net.Proxy.Type</span>;
<span class="keyword">import</span> <span class="include">java.util.concurrent.TimeUnit</span>;

<span class="type">class</span> <span class="class">MapDemo</span> {
    <span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-p</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--proxyHost</span><span class="delimiter">&quot;</span></span>})
    <span class="predefined-type">Map</span>&lt;<span class="predefined-type">Proxy</span>.Type, <span class="predefined-type">InetAddress</span>&gt; proxies;

    <span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-u</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--timeUnit</span><span class="delimiter">&quot;</span></span>})
    <span class="predefined-type">Map</span>&lt;<span class="predefined-type">TimeUnit</span>, <span class="predefined-type">Long</span>&gt; timeout;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Map options may be specified multiple times with different key-value pairs. (See <a href="#_multiple_values">Multiple Values</a>.)</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">&lt;command&gt; -p HTTP=123.123.123.123 --proxyHost SOCKS=212.212.212.212
&lt;command&gt; -uDAYS=3 -u HOURS=23 -u=MINUTES=59 --timeUnit=SECONDS=13</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the field is <code>null</code>, picocli will instantiate it when the option or positional parameter is matched.
If the type is not a concrete class, picocli will instantiate a <code>LinkedHashMap</code> to preserve the input ordering.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
On the command line, the key and the value must be separated by a <code>=</code> character.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Map options and positional parameters can be defined with a <code>split</code> regular expression to allow end users to specify multiple values in a single parameter.
See the <a href="#_split_regex">Split Regex</a> section for details.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_abstract_field_types">4.6. Abstract Field Types</h3>
<div class="paragraph">
<p>The field&#8217;s type can be an interface or an abstract class.
The <code>type</code> attribute can be used to control for each field what concrete class the string value should be converted to.
For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">App</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">--big</span><span class="delimiter">&quot;</span></span>, type = <span class="predefined-type">BigDecimal</span>.class) <span class="comment">// concrete Number subclass</span>
    <span class="predefined-type">Number</span><span class="type">[]</span> big; <span class="comment">// array type with abstract component class</span>

    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">--small</span><span class="delimiter">&quot;</span></span>, type = <span class="predefined-type">Short</span>.class) <span class="comment">// other Number subclass</span>
    <span class="predefined-type">Number</span><span class="type">[]</span> small;

    <span class="annotation">@Parameters</span>(type = <span class="predefined-type">StringBuilder</span>.class) <span class="comment">// StringBuilder implements CharSequence</span>
    <span class="predefined-type">CharSequence</span> address; <span class="comment">// interface type</span>
}</code></pre>
</div>
</div>
<div class="sect3">
<h4 id="_maps_and_collections_with_abstract_elements">4.6.1. Maps and Collections with Abstract Elements</h4>
<div class="paragraph">
<p>For raw maps and collections, or when using generics with unbounded wildcards like <code>Map&lt;?, ?&gt;</code>, or when the type parameters are themselves abstract classes like <code>List&lt;CharSequence&gt;</code> or <code>Map&lt;? extends Number, ? super Number&gt;</code>, there is not enough information to convert to a stronger type. By default, the raw String values are added as is to such collections.</p>
</div>
<div class="paragraph">
<p>The <code>type</code> attribute can be specified to convert to a stronger type than String. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">TypeDemo</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>)  <span class="comment">// not enough information to convert</span>
    <span class="predefined-type">Map</span>&lt;?, ?&gt; weaklyTyped; <span class="comment">// String keys and values are added as is</span>

    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-y</span><span class="delimiter">&quot;</span></span>, type = {<span class="predefined-type">Short</span>.class, <span class="predefined-type">BigDecimal</span>.class})
    <span class="predefined-type">Map</span>&lt;? <span class="directive">extends</span> <span class="predefined-type">Number</span>, ? <span class="local-variable">super</span> <span class="predefined-type">Number</span>&gt; stronglyTyped;

    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-s</span><span class="delimiter">&quot;</span></span>, type = <span class="predefined-type">CharBuffer</span>.class)
    <span class="predefined-type">List</span>&lt;<span class="predefined-type">CharSequence</span>&gt; text;
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_enum_types">4.7. Enum Types</h3>
<div class="paragraph">
<p>It is encouraged to use <code>enum</code> types for options or positional parameters with a limited set of valid values.
Not only will picocli validate the input, it allows you to <a href="#_show_default_values">show all values</a> in the usage help message with <code>@Option(description = "Valid values: ${COMPLETION-CANDIDATES}")</code>. It also allows command line completion to suggest completion candidates for the values of this option.</p>
</div>
<div class="paragraph">
<p>Enum value matching is case-sensitive by default, but from 3.4 this can be controlled with <code>CommandLine::setCaseInsensitiveEnumValuesAllowed</code> and <code>CommandSpec::caseInsensitiveEnumValuesAllowed</code>.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_default_values">5. Default Values</h2>
<div class="sectionbody">
<div class="paragraph">
<p>It is possible to define a default value for an option or positional parameter, that is assigned when the user did not specify this option or positional parameter on the command line.</p>
</div>
<div class="sect2">
<h3 id="defaultValue-annotation">5.1. <code>defaultValue</code> Annotation</h3>
<div class="paragraph">
<p>The recommended way to give an option or positional parameter a default value is to use the <code>defaultValue</code> annotation attribute. This works correctly with argument groups, <code>@Option</code> and <code>@Parameters</code>-annotated methods, and allows annotation processors to detect and use default values.</p>
</div>
<div class="paragraph">
<p>For <a href="#option-parameters-methods">@Option and @Parameters-annotated methods</a> and <a href="#command-methods">@Command-annotated methods</a>, there is no alternative but to use the <code>defaultValue</code> annotation attribute. For example, for an annotated interface:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">interface</span> <span class="class">Spec</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-c</span><span class="delimiter">&quot;</span></span>, defaultValue = <span class="string"><span class="delimiter">&quot;</span><span class="content">123</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">... ${DEFAULT-VALUE} ...</span><span class="delimiter">&quot;</span></span>)
    <span class="type">int</span> count();
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Example of using the <code>defaultValue</code> attribute in the option of a command method:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">CommandMethod</span> {
    <span class="annotation">@Command</span>(description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Do something.</span><span class="delimiter">&quot;</span></span>)
    <span class="type">void</span> doit(<span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-c</span><span class="delimiter">&quot;</span></span>, defaultValue = <span class="string"><span class="delimiter">&quot;</span><span class="content">123</span><span class="delimiter">&quot;</span></span>) <span class="type">int</span> count) {
        <span class="comment">// ...</span>
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that you can use the <code>${DEFAULT-VALUE}</code> <a href="#_predefined_variables">variable</a> in the <code>description</code> of the option or positional parameter and picocli will <a href="#_show_default_values">show</a> the actual default value.</p>
</div>
</div>
<div class="sect2">
<h3 id="_field_values">5.2. Field Values</h3>
<div class="paragraph">
<p>For annotated fields, it is possible to declare the field with a value:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-c</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">The count (default: ${DEFAULT-VALUE})</span><span class="delimiter">&quot;</span></span>)
<span class="type">int</span> count = <span class="integer">123</span>; <span class="comment">// default value is 123</span></code></pre>
</div>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Defining a default value by assigning a value at the field declaration has limitations:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>when the option is used in a argument group, the usage help <a href="#_default_values_in_argument_groups">cannot show the default value</a></p>
</li>
<li>
<p>picocli&#8217;s annotation processors can only detect default values in annotations, not in the field declaration. Your application may not work correctly with future features like documentation generated from the annotations.</p>
</li>
</ul>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_default_provider">5.3. Default Provider</h3>
<div class="paragraph">
<p>Finally, you can specify a default provider in the <code>@Command</code> annotation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(defaultValueProvider = MyDefaultProvider.class)
<span class="type">class</span> <span class="class">MyCommand</span> <span class="comment">// ...</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>The default provider allows you to get default values from a configuration file or some other central place.
Default providers need to implement the <code>picocli.CommandLine.IDefaultValueProvider</code> interface:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">IDefaultValueProvider</span> {

    <span class="comment">/**
     * Returns the default value for an option or positional parameter or {@code null}.
     * The returned value is converted to the type of the option/positional parameter
     * via the same type converter used when populating this option/positional
     * parameter from a command line argument.
     *
     * @param argSpec the option or positional parameter, never {@code null}
     * @return the default value for the option or positional parameter, or {@code null} if
     *       this provider has no default value for the specified option or positional parameter
     * @throws Exception when there was a problem obtaining the default value
     */</span>
    <span class="predefined-type">String</span> defaultValue(ArgSpec argSpec) <span class="directive">throws</span> <span class="exception">Exception</span>;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>See the
<a href="https://github.com/remkop/picocli/blob/master/picocli-examples/src/main/java/picocli/examples/defaultprovider/">default provider examples</a>
for example implementations.</p>
</div>
</div>
<div class="sect2">
<h3 id="_propertiesdefaultprovider">5.4. PropertiesDefaultProvider</h3>
<div class="paragraph">
<p>From picocli 4.1, applications can use the built-in <code>PropertiesDefaultProvider</code>
implementation that loads default values from a properties file.</p>
</div>
<div class="paragraph">
<p>By default, this implementation tries to find a properties file named <code>.${COMMAND-NAME}.properties</code> in the user home directory, where <code>${COMMAND-NAME}</code> is the name of the command. If a command has aliases in addition to its name, these aliases are also used to try to find the properties file. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">picocli.CommandLine.PropertiesDefaultProvider</span>;
<span class="comment">// ...</span>
<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">git</span><span class="delimiter">&quot;</span></span>, defaultValueProvider = PropertiesDefaultProvider.class)
<span class="type">class</span> <span class="class">Git</span> { }</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above will try to load default values from <code>new File(System.getProperty("user.home"), ".git.properties")</code>.
The location of the properties file can also be controlled with system property <code>"picocli.defaults.${COMMAND-NAME}.path"</code> (<code>"picocli.defaults.git.path"</code> in this example), in which case the value of the property must be the path to the file containing the default values.</p>
</div>
<div class="paragraph">
<p>The location of the properties file may also be specified programmatically. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">CommandLine cmd = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MyCommand());
<span class="predefined-type">File</span> defaultsFile = <span class="keyword">new</span> <span class="predefined-type">File</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">path/to/config/mycommand.properties</span><span class="delimiter">&quot;</span></span>);
cmd.setDefaultValueProvider(<span class="keyword">new</span> PropertiesDefaultProvider(defaultsFile));
cmd.execute(args);</code></pre>
</div>
</div>
<div class="sect3">
<h4 id="_propertiesdefaultprovider_format">5.4.1. PropertiesDefaultProvider Format</h4>
<div class="paragraph">
<p>The <code>PropertiesDefaultProvider</code> expects the properties file to be in the standard java <code>.properties</code> <a href="https://en.wikipedia.org/wiki/.properties">format</a>.</p>
</div>
<div class="paragraph">
<p>For options, the key is either the <a href="https://picocli.info/apidocs/picocli/CommandLine.Option.html#descriptionKey--">descriptionKey</a>,
or the option&#8217;s <a href="https://picocli.info/apidocs/picocli/CommandLine.Model.OptionSpec.html#longestName--">longest name</a>, without the prefix. So, for an option <code>--verbose</code>, the key would be <code>verbose</code>, and for an option <code>/F</code>, the key would be <code>F</code>.</p>
</div>
<div class="paragraph">
<p>For positional parameters, the key is either the <a href="https://picocli.info/apidocs/picocli/CommandLine.Parameters.html#descriptionKey--">descriptionKey</a>,
or the positional parameter&#8217;s <a href="https://picocli.info/apidocs/picocli/CommandLine.Parameters.html#paramLabel--">param label</a>.</p>
</div>
<div class="paragraph">
<p>End users may not know what the <code>descriptionKey</code> of your options and positional parameters are, so be sure  to document that with your application.</p>
</div>
</div>
<div class="sect3">
<h4 id="_subcommands_default_values">5.4.2. Subcommands Default Values</h4>
<div class="paragraph">
<p>The default values for options and positional parameters of subcommands can be included in the
properties file for the top-level command, so that end users need to maintain only a single file.
This can be achieved by prefixing the keys for the options and positional parameters
with their command&#8217;s qualified name.
For example, to give the  <code>git commit</code> command&#8217;s <code>--cleanup</code> option a
default value of <code>strip</code>, define a key of <code>git.commit.cleanup</code> and assign
it a default value:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code># /home/remko/.git.properties
git.commit.cleanup = strip</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="fallbackValue-annotation">5.5. <code>fallbackValue</code> Annotation</h3>
<div class="paragraph">
<p>If an option is defined with <code>arity = "0..1"</code>, it may or not have a parameter value.
If such an option is specified without a value on the command line, it is assigned the fallback value.</p>
</div>
<div class="paragraph">
<p>The <code>fallbackValue</code> annotation attribute was introduced in picocli 4.0; prior to this, (from picocli 2.3) an empty String was assigned.</p>
</div>
<div class="paragraph">
<p>This is different from the <code>defaultValue</code>, which is assigned if the option is not specified at all on the command line.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">FallbackValueDemo</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>, arity = <span class="string"><span class="delimiter">&quot;</span><span class="content">0..1</span><span class="delimiter">&quot;</span></span>,
            defaultValue = <span class="string"><span class="delimiter">&quot;</span><span class="content">-1</span><span class="delimiter">&quot;</span></span>, fallbackValue = <span class="string"><span class="delimiter">&quot;</span><span class="content">-2</span><span class="delimiter">&quot;</span></span>,
            description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Option with optional parameter. Default: ${DEFAULT-VALUE}, </span><span class="delimiter">&quot;</span></span> +
                          <span class="string"><span class="delimiter">&quot;</span><span class="content">if specified without parameter: ${FALLBACK-VALUE}</span><span class="delimiter">&quot;</span></span>)
    <span class="type">int</span> x;

    <span class="directive">public</span> <span class="type">void</span> run() { <span class="predefined-type">System</span>.out.printf(<span class="string"><span class="delimiter">&quot;</span><span class="content">x = %s%n</span><span class="delimiter">&quot;</span></span>, x); }

    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span>... args) {
       <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> FallbackValueDemo()).execute(args);
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Gives the following results:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">java FallbackValueDemo -x 100
x = 100

java FallbackValueDemo -x
x = -2

java FallbackValueDemo
x = -1</code></pre>
</div>
</div>
<div class="paragraph">
<p>Any String value is converted to the type of the option before it is assigned to the option. Options and positional parameters may define a <a href="#_custom_type_converters">custom type converter</a> if necessary.</p>
</div>
<div class="paragraph">
<p>Note that the option description may contain the <code>${FALLBACK-VALUE}</code> <a href="#_predefined_variables">variable</a> which will be replaced with the actual fallback value when the usage help is shown.</p>
</div>
<div class="paragraph">
<p><a href="#_boolean_options">Boolean options</a> can also define a <code>fallbackValue</code> to specify the value that should be set when the option is matched on the command line, regardless of the default value. This can be useful when the default is configurable by the end user, for example.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_multiple_values">6. Multiple Values</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Multi-valued options and positional parameters are annotated fields that can capture multiple values from the command line.</p>
</div>
<div class="sect2">
<h3 id="_multiple_occurrences">6.1. Multiple Occurrences</h3>
<div class="sect3">
<h4 id="_repeated_options">6.1.1. Repeated Options</h4>
<div class="paragraph">
<p>The simplest way to create a multi-valued option is to declare an annotated field whose type is an array, collection or a map.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-option</span><span class="delimiter">&quot;</span></span>)
<span class="type">int</span><span class="type">[]</span> values;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Users may specify the same option multiple times. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>&lt;command&gt; -option 111 -option 222 -option 333</pre>
</div>
</div>
<div class="paragraph">
<p>Each value is appended to the array or collection.</p>
</div>
</div>
<div class="sect3">
<h4 id="_multiple_positional_parameters">6.1.2. Multiple Positional Parameters</h4>
<div class="paragraph">
<p>Similarly for multi-valued positional parameters:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Parameters</span>
<span class="predefined-type">List</span>&lt;<span class="predefined-type">TimeUnit</span>&gt; units;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Users may specify multiple positional parameters. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>&lt;command&gt; SECONDS HOURS DAYS</pre>
</div>
</div>
<div class="paragraph">
<p>Again, each value is appended to the array or collection.</p>
</div>
</div>
<div class="sect3">
<h4 id="_repeated_boolean_options">6.1.3. Repeated Boolean Options</h4>
<div class="paragraph">
<p>Boolean options with multiple values are supported from picocli 2.1.0.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-v</span><span class="delimiter">&quot;</span></span>, description = { <span class="string"><span class="delimiter">&quot;</span><span class="content">Specify multiple -v options to increase verbosity.</span><span class="delimiter">&quot;</span></span>,
                                      <span class="string"><span class="delimiter">&quot;</span><span class="content">For example, `-v -v -v` or `-vvv`</span><span class="delimiter">&quot;</span></span>})
<span class="type">boolean</span><span class="type">[]</span> verbosity;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Users may specify multiple boolean flag options without parameters. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>&lt;command&gt; -v -v -v -vvv</pre>
</div>
</div>
<div class="paragraph">
<p>The above example results in six <code>true</code> values being added to the <code>verbosity</code> array.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_split_regex">6.2. Split Regex</h3>
<div class="paragraph">
<p>Options and parameters may also specify a <code>split</code> regular expression used to split each option parameter into smaller substrings.
Each of these substrings is converted to the type of the collection or array. See <a href="#_arrays_and_collections">Arrays and Collections</a>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-option</span><span class="delimiter">&quot;</span></span>, split = <span class="string"><span class="delimiter">&quot;</span><span class="content">,</span><span class="delimiter">&quot;</span></span>)
<span class="type">int</span><span class="type">[]</span> values;</code></pre>
</div>
</div>
<div class="paragraph">
<p>A single command line argument like the following will be split up and three <code>int</code> values are added to the array:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>-option 111,222,333</pre>
</div>
</div>
<div class="paragraph">
<p>Similarly for <a href="#_maps">Maps</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-fix</span><span class="delimiter">&quot;</span></span>, split = <span class="string"><span class="delimiter">&quot;</span><span class="char">\\</span><span class="content">|</span><span class="delimiter">&quot;</span></span>)
<span class="predefined-type">Map</span>&lt;<span class="predefined-type">Integer</span>, <span class="predefined-type">String</span>&gt; message;</code></pre>
</div>
</div>
<div class="paragraph">
<p>With the above option, command line arguments like the following are interpreted as a set of key-value pairs instead of a single string:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>-fix 8=FIX.4.4|9=69|35=A|49=MBT|56=TargetCompID|34=9|52=20130625-04:05:32.682|98=0|108=30|10=052</pre>
</div>
</div>
<div class="paragraph">
<p>The above input results in the <code>message</code> field being assigned a <code>LinkedHashMap</code> with the following key-value pairs:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>{8=FIX.4.4, 9=69, 35=A, 49=MBT, 56=TargetCompID, 34=9, 52=20130625-04:05:32.682, 98=0, 108=30, 10=052}</pre>
</div>
</div>
<div class="paragraph">
<p>See <a href="#_quoted_values">Quoted Values</a> for details on handling more complex cases.</p>
</div>
</div>
<div class="sect2">
<h3 id="_arity">6.3. Arity</h3>
<div class="paragraph">
<p>Sometimes you want to define an option that requires more than one option parameter <em>for each option occurrence</em> on the command line.</p>
</div>
<div class="paragraph">
<p>The <code>arity</code> attribute lets you control exactly how many parameters to consume for each option occurrence.</p>
</div>
<div class="paragraph">
<p>The <code>arity</code> attribute can specify an exact number of required parameters, or a <em>range</em> with a minimum and a maximum number of parameters.
The maximum can be an exact upper bound, or it can be <code>"*"</code> to denote <em>any number</em> of parameters. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">ArityDemo</span> {
    <span class="annotation">@Parameters</span>(arity = <span class="string"><span class="delimiter">&quot;</span><span class="content">1..3</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">one to three Files</span><span class="delimiter">&quot;</span></span>)
    <span class="predefined-type">File</span><span class="type">[]</span> files;

    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-f</span><span class="delimiter">&quot;</span></span>, arity = <span class="string"><span class="delimiter">&quot;</span><span class="content">2</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">exactly two floating point numbers</span><span class="delimiter">&quot;</span></span>)
    <span class="type">double</span><span class="type">[]</span> doubles;

    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-s</span><span class="delimiter">&quot;</span></span>, arity = <span class="string"><span class="delimiter">&quot;</span><span class="content">1..*</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">at least one string</span><span class="delimiter">&quot;</span></span>)
    <span class="predefined-type">String</span><span class="type">[]</span> strings;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>A <code>MissingParameterException</code> is thrown when fewer than the minimum number of parameters is specified on the command line.</p>
</div>
<div class="paragraph">
<p>Once the minimum number of parameters is consumed, picocli will check each subsequent command line argument to see whether it is an additional parameter, or a new option. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>ArityDemo -s A B C -f 1.0 2.0 /file1 /file2</pre>
</div>
</div>
<div class="paragraph">
<p>Option <code>-s</code> has arity <code>"1..*"</code> but instead of consuming all parameters,
the <code>-f</code> argument is recognized as a separate option.</p>
</div>
</div>
<div class="sect2">
<h3 id="_default_arity">6.4. Default Arity</h3>
<div class="paragraph">
<p>If no <code>arity</code> is specified, the number of parameters depends on the field&#8217;s type.</p>
</div>
<div class="sect3">
<h4 id="_option_arity">6.4.1. Option Arity</h4>
<table class="tableblock frame-all grid-cols stretch">
<caption class="title">Table 1. Default <code>arity</code> for <code>@Option</code> fields</caption>
<colgroup>
<col style="width: 30%;">
<col style="width: 5%;">
<col style="width: 65%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">@Option Field Type</th>
<th class="tableblock halign-left valign-top">Default Arity</th>
<th class="tableblock halign-left valign-top">Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">boolean</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean options by default don&#8217;t require an option parameter. The field is set to the opposite of its default value when the option name is recognized. (This can be <a href="#_toggle_boolean_flags">configured</a>.)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Single-valued type (e.g., <code>int</code>, <code>String</code>, <code>File</code>)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The option name must be followed by a value.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Multi-valued type (arrays, collections or maps)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The option name must be followed by a value.</p></td>
</tr>
</tbody>
</table>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
Prior to picocli 2.0, multi-valued options used to greedily consume as many arguments as possible until
encountering another option or subcommand.
If your application relies on the previous behaviour, you need to explicitly specify an option arity of <code>0..*</code> when migrating to picocli 2.0.
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="_positional_parameter_arity">6.4.2. Positional Parameter Arity</h4>
<table class="tableblock frame-all grid-cols stretch">
<caption class="title">Table 2. Default <code>arity</code> for <code>@Parameters</code> fields</caption>
<colgroup>
<col style="width: 30%;">
<col style="width: 5%;">
<col style="width: 65%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">@Parameters Field Type</th>
<th class="tableblock halign-left valign-top">Default Arity</th>
<th class="tableblock halign-left valign-top">Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">boolean</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Positional parameters of type <code>boolean</code> or <code>Boolean</code> require a value. Only <code>true</code> or <code>false</code> (case insensitive) are valid values.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Single-valued type (e.g., <code>int</code>, <code>String</code>, <code>File</code>)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">One parameter required for each position.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Multi-valued type (arrays, collections or maps)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">0..1</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">For multi-valued positional parameters (arrays, collections or maps), values are optional, not required.</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p><code>@Parameters</code> fields are applied to a command line argument if their index matches the argument&#8217;s position.
The default index is <code>*</code>, meaning all positions.
A <code>@Parameters</code> field with <code>index = "*"</code> is applied multiple times: once for each positional parameter on the command line.</p>
</div>
<div class="paragraph">
<p>When a <code>@Parameters</code> field is applied (because its index matches the index of the positional parameter), the field may consume zero, one or more arguments, depending on its arity.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_optional_values">6.5. Optional Values</h3>
<div class="paragraph">
<p>If an option is defined with <code>arity = "0..1"</code>, it may or not have a parameter value.
If such an option is specified without a value on the command line, it is assigned the <a href="#fallbackValue-annotation">fallback value</a>.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_required_arguments">7. Required Arguments</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_required_options">7.1. Required Options</h3>
<div class="paragraph">
<p>Options can be marked <code>required</code> to make it mandatory for the user to specify them on the command line. When a required option is not specified, a <code>MissingParameterException</code> is thrown from the <code>parse</code> method. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">MandatoryOption</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-n</span><span class="delimiter">&quot;</span></span>, required = <span class="predefined-constant">true</span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">mandatory number</span><span class="delimiter">&quot;</span></span>)
    <span class="type">int</span> number;

    <span class="annotation">@Parameters</span>
    <span class="predefined-type">File</span><span class="type">[]</span> files;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The following command line arguments would result in an exception complaining that <code>number</code> is missing:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>// invalid: missing option -n
&lt;command&gt; file1 file2 file3</pre>
</div>
</div>
<div class="paragraph">
<p>The following command line arguments would be accepted:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>// valid: required option -n has a value
&lt;command&gt; -n 123 file1 file2 file3</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_required_parameters">7.2. Required Parameters</h3>
<div class="paragraph">
<p>Single-value <code>@Parameters</code> are always mandatory, because single-value positional parameters <a href="#_positional_parameter_arity">have <code>arity = "1"</code></a> by default.</p>
</div>
<div class="paragraph">
<p>The <code>arity</code> attribute can be used to make multi-value <code>@Parameters</code> mandatory:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">BothOptionAndParametersMandatory</span> {
    <span class="annotation">@Parameters</span>(arity = <span class="string"><span class="delimiter">&quot;</span><span class="content">1..*</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">at least one File</span><span class="delimiter">&quot;</span></span>)
    <span class="predefined-type">File</span><span class="type">[]</span> files;

    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-n</span><span class="delimiter">&quot;</span></span>, required = <span class="predefined-constant">true</span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">mandatory number</span><span class="delimiter">&quot;</span></span>)
    <span class="type">int</span> number;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The following command line arguments would result in an exception complaining that <code>files</code> are missing:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>// invalid: missing file parameters
&lt;command&gt; -n 123</pre>
</div>
</div>
<div class="paragraph">
<p>The following command line arguments would be accepted:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>// valid: both required fields have a value
&lt;command&gt; -n 123 file1</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_options_with_an_optional_parameter">7.3. Options with an Optional Parameter</h3>
<div class="paragraph">
<p>Options with <code>arity = "0..1"</code> have an optional parameter.
This can be useful for <a href="#_optionally_interactive">password options</a> and in some other cases.</p>
</div>
<div class="paragraph">
<p>The <a href="#fallbackValue-annotation">fallback value</a> determines what value is assigned when the option is specified without a value, while the <a href="#defaultValue-annotation">default value</a> determines what value is assigned when the option is not specified at all.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Be careful when defining commands that have both an option with an optional parameter and a positional parameter.</p>
</div>
<div class="paragraph">
<p>The picocli parser is "greedy" when it handles optional parameters: it looks at the value following the option name, and if that value is likely to be a parameter (not another option or subcommand) then it will process the value as a parameter for that option. This may not always be what you want.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">Ambiguous</span> {
    <span class="annotation">@Parameters</span>(description = <span class="string"><span class="delimiter">&quot;</span><span class="content">The file (required).</span><span class="delimiter">&quot;</span></span>)
    <span class="predefined-type">File</span> file;

    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>, arity = <span class="string"><span class="delimiter">&quot;</span><span class="content">0..1</span><span class="delimiter">&quot;</span></span>,
      description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Option with optional parameter</span><span class="delimiter">&quot;</span></span>)
    <span class="predefined-type">String</span> value;

    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-y</span><span class="delimiter">&quot;</span></span>, arity = <span class="string"><span class="delimiter">&quot;</span><span class="content">0..*</span><span class="delimiter">&quot;</span></span>,
      description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Option with optional parameters</span><span class="delimiter">&quot;</span></span>)
    <span class="predefined-type">List</span>&lt;<span class="predefined-type">String</span>&gt; values;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>When <code>-x VALUE</code> is specified on the command line, this results in an error: <code>Missing required parameter: &lt;file&gt;</code>. Similarly, when <code>-y a b c path/to/file</code> is specified.</p>
</div>
<div class="paragraph">
<p>Users can use the <a href="#_double_dash">end-of-options delimiter</a> and disambiguate the input with
 <code>-x &dash;&dash; VALUE</code> or <code>-y a b c &dash;&dash; VALUE</code>, but this may not be obvious to many users.</p>
</div>
<div class="paragraph">
<p>A better alternative may be to redesign your command to avoid the ambiguity altogether.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_argument_groups">8. Argument Groups</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Picocli 4.0 introduces a new <code>@ArgGroup</code> annotation and its <code>ArgGroupSpec</code> programmatic equivalent.</p>
</div>
<div class="paragraph">
<p>Argument Groups can be used to define:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>mutually exclusive options</p>
</li>
<li>
<p>options that must co-occur (dependent options)</p>
</li>
<li>
<p>option sections in the usage help message</p>
</li>
<li>
<p>repeating composite arguments</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>To create a group using the annotations API, annotate a field or method with <code>@ArgGroup</code>.
The field&#8217;s type refers to the class containing the options and positional parameters in the group.
(For annotated interface methods this would be the return type, for annotated setter methods in a concrete class this would be the setter&#8217;s parameter type.)</p>
</div>
<div class="paragraph">
<p>Picocli will instantiate this class when needed to capture command line argument values in the <code>@Option</code> and <code>@Parameters</code>-annotated fields and methods of this class.</p>
</div>
<div class="sect2">
<h3 id="_mutually_exclusive_options">8.1. Mutually Exclusive Options</h3>
<div class="paragraph">
<p>Annotate a field or method with <code>@ArgGroup(exclusive = true)</code> to create a group of mutually exclusive options and positional parameters. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">exclusivedemo</span><span class="delimiter">&quot;</span></span>)
<span class="directive">public</span> <span class="type">class</span> <span class="class">MutuallyExclusiveOptionsDemo</span> {

    <span class="annotation">@ArgGroup</span>(exclusive = <span class="predefined-constant">true</span>, multiplicity = <span class="string"><span class="delimiter">&quot;</span><span class="content">1</span><span class="delimiter">&quot;</span></span>)
    Exclusive exclusive;

    <span class="directive">static</span> <span class="type">class</span> <span class="class">Exclusive</span> {
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-a</span><span class="delimiter">&quot;</span></span>, required = <span class="predefined-constant">true</span>) <span class="type">int</span> a;
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-b</span><span class="delimiter">&quot;</span></span>, required = <span class="predefined-constant">true</span>) <span class="type">int</span> b;
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-c</span><span class="delimiter">&quot;</span></span>, required = <span class="predefined-constant">true</span>) <span class="type">int</span> c;
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above example defines a command with mutually exclusive options <code>-a</code>, <code>-b</code> and <code>-c</code>.</p>
</div>
<div class="paragraph">
<p>The group itself has a <code>multiplicity</code> attribute that defines how many times the group may be specified within the command.
The default is <code>multiplicity = "0..1"</code>, meaning that by default a group may be omitted or specified once.
In this example the group has <code>multiplicity = "1"</code>, so the group must occur once: one of the exclusive options must occur on the command line.</p>
</div>
<div class="paragraph">
<p>The synopsis of this command is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: exclusivedemo (-a=&lt;a&gt; | -b=&lt;b&gt; | -c=&lt;c&gt;)</pre>
</div>
</div>
<div class="paragraph">
<p>When one of the options in the group is matched, picocli creates an instance of the <code>Exclusive</code> class and assigns it to the <code>@ArgGroup</code>-annotated <code>exclusive</code> field.</p>
</div>
<div class="paragraph">
<p>Note that the options are defined as <code>required = true</code>; this means required <em>within the group</em>, not required within the command.</p>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
From picocli 4.1.2, all options in an exclusive group are automatically considered required, even if they are not marked as <code>required = true</code> in the annotations. Applications using older versions of picocli should mark all options in exclusive groups as required.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Picocli will validate the arguments and throw a <code>MutuallyExclusiveArgsException</code> if multiple mutually exclusive arguments were specified. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">MutuallyExclusiveOptionsDemo example = <span class="keyword">new</span> MutuallyExclusiveOptionsDemo();
CommandLine cmd = <span class="keyword">new</span> CommandLine(example);

<span class="keyword">try</span> {
    cmd.parseArgs(<span class="string"><span class="delimiter">&quot;</span><span class="content">-a=1</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">-b=2</span><span class="delimiter">&quot;</span></span>);
} <span class="keyword">catch</span> (MutuallyExclusiveArgsException ex) {
    <span class="keyword">assert</span> <span class="string"><span class="delimiter">&quot;</span><span class="content">Error: -a=&lt;a&gt;, -b=&lt;b&gt; are mutually exclusive (specify only one)</span><span class="delimiter">&quot;</span></span>
            .equals(ex.getMessage());
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>For the above group, only one of the options can be specified. Any other combination of options, or the absence of options, is invalid.</p>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
Picocli will not initialize the <code>@ArgGroup</code>-annotated field
if none of the group options is specified on the command line.
For optional groups (groups with <code>multiplicity = "0..1"</code> - the default) this means that the <code>@ArgGroup</code>-annotated field may remain <code>null</code>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_mutually_dependent_options">8.2. Mutually Dependent Options</h3>
<div class="sect3">
<h4 id="_overview">8.2.1. Overview</h4>
<div class="paragraph">
<p>Annotate a field or method with <code>@ArgGroup(exclusive = false)</code> to create a group of dependent options and positional parameters that must co-occur. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">co-occur</span><span class="delimiter">&quot;</span></span>)
<span class="directive">public</span> <span class="type">class</span> <span class="class">DependentOptionsDemo</span> {

    <span class="annotation">@ArgGroup</span>(exclusive = <span class="predefined-constant">false</span>)
    Dependent dependent;

    <span class="directive">static</span> <span class="type">class</span> <span class="class">Dependent</span> {
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-a</span><span class="delimiter">&quot;</span></span>, required = <span class="predefined-constant">true</span>) <span class="type">int</span> a;
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-b</span><span class="delimiter">&quot;</span></span>, required = <span class="predefined-constant">true</span>) <span class="type">int</span> b;
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-c</span><span class="delimiter">&quot;</span></span>, required = <span class="predefined-constant">true</span>) <span class="type">int</span> c;
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above example defines a command with dependent options <code>-a</code>, <code>-b</code> and <code>-c</code> that must co-occur.</p>
</div>
<div class="paragraph">
<p>The group itself has a <code>multiplicity</code> attribute that defines how many times the group may be specified within the command.
In this example the group uses the default multiplicity, <code>multiplicity = "0..1"</code>, meaning that the group may be omitted or specified once.</p>
</div>
<div class="paragraph">
<p>The synopsis of this command is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: co-occur [-a=&lt;a&gt; -b=&lt;b&gt; -c=&lt;c&gt;]</pre>
</div>
</div>
<div class="paragraph">
<p>When the first option in the group is matched, picocli creates an instance of the <code>Dependent</code> class and assigns it to the <code>@ArgGroup</code>-annotated <code>dependent</code> field.</p>
</div>
<div class="paragraph">
<p>Note that the options are defined as <code>required = true</code>; this means required <em>within the group</em>, not required within the command.</p>
</div>
<div class="paragraph">
<p>Picocli will validate the arguments and throw a <code>MissingParameterException</code> if not all dependent arguments were specified. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">DependentOptionsDemo example = <span class="keyword">new</span> DependentOptionsDemo();
CommandLine cmd = <span class="keyword">new</span> CommandLine(example);

<span class="keyword">try</span> {
    cmd.parseArgs(<span class="string"><span class="delimiter">&quot;</span><span class="content">-a=1</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">-b=2</span><span class="delimiter">&quot;</span></span>);
} <span class="keyword">catch</span> (MissingParameterException ex) {
    <span class="keyword">assert</span> <span class="string"><span class="delimiter">&quot;</span><span class="content">Error: Missing required argument(s): -c=&lt;c&gt;</span><span class="delimiter">&quot;</span></span>.equals(ex.getMessage());
}</code></pre>
</div>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
Picocli will not initialize the <code>@ArgGroup</code>-annotated field
if none of the group options is specified on the command line.
For optional groups (groups with <code>multiplicity = "0..1"</code> - the default) this means that the <code>@ArgGroup</code>-annotated field may remain <code>null</code>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="_non_required_options_in_mutually_dependent_groups">8.2.2. Non-Required Options in Mutually Dependent Groups</h4>
<div class="paragraph">
<p>In mutually dependent groups it is possible to have one or more options that are not required. This is different from <a href="#_mutually_exclusive_options">exclusive groups</a>, where all options are always required.</p>
</div>
<div class="paragraph">
<p>It is useful to be able to define a co-occurring group as <code>(-a -b [-c])</code> so that both <code>-a -b -c</code> and <code>-a -b</code> are valid on the command line, but not <code>-a -c</code> for example.
This can be implemented by marking the optional option with <code>required = false</code>, as in the below example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">co-occur-with-optional-options</span><span class="delimiter">&quot;</span></span>)
<span class="directive">public</span> <span class="type">class</span> <span class="class">DependentWithOptionalOptionsDemo</span> {

    <span class="annotation">@ArgGroup</span>(exclusive = <span class="predefined-constant">false</span>, multiplicity = <span class="string"><span class="delimiter">&quot;</span><span class="content">1</span><span class="delimiter">&quot;</span></span>)
    DependentWithOptionalOptions group;

    <span class="directive">static</span> <span class="type">class</span> <span class="class">DependentWithOptionalOptions</span> {
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-a</span><span class="delimiter">&quot;</span></span>, required = <span class="predefined-constant">true</span>) <span class="type">int</span> a;
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-b</span><span class="delimiter">&quot;</span></span>, required = <span class="predefined-constant">true</span>) <span class="type">int</span> b;
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-c</span><span class="delimiter">&quot;</span></span>, required = <span class="predefined-constant">false</span>) <span class="type">int</span> c;
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>More than one option can be optional in mutually dependent groups, but it is recommended to have at least one required option in the group (or there is not much point in using a mutually dependent group).</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_option_sections_in_usage_help">8.3. Option Sections in Usage Help</h3>
<div class="sect3">
<h4 id="_use_heading_to_enable_option_sections">8.3.1. Use Heading to Enable Option Sections</h4>
<div class="paragraph">
<p>The example below uses groups to define options sections in the usage help.
When a group has a non-null <code>heading</code> (or <code>headingKey</code>), the options in the group are given the specified heading in the usage help message.
The <code>headingKey</code> attribute can be used to get the heading text from the command&#8217;s resource bundle.</p>
</div>
<div class="paragraph">
<p>This works for mutually exclusive or co-occurring groups, but it is also possible to define a group that does no validation but only creates an option section in the usage help.</p>
</div>
<div class="paragraph">
<p>Annotate a field or method with <code>@ArgGroup(validate = false)</code> to create a group for display purposes only. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">sectiondemo</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Section demo</span><span class="delimiter">&quot;</span></span>)
<span class="directive">public</span> <span class="type">class</span> <span class="class">OptionSectionDemo</span> {

    <span class="annotation">@ArgGroup</span>(validate = <span class="predefined-constant">false</span>, heading = <span class="string"><span class="delimiter">&quot;</span><span class="content">This is the first section%n</span><span class="delimiter">&quot;</span></span>)
    Section1 section1;

    <span class="directive">static</span> <span class="type">class</span> <span class="class">Section1</span> {
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-a</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Option A</span><span class="delimiter">&quot;</span></span>) <span class="type">int</span> a;
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-b</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Option B</span><span class="delimiter">&quot;</span></span>) <span class="type">int</span> b;
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-c</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Option C</span><span class="delimiter">&quot;</span></span>) <span class="type">int</span> c;
    }

    <span class="annotation">@ArgGroup</span>(validate = <span class="predefined-constant">false</span>, heading = <span class="string"><span class="delimiter">&quot;</span><span class="content">This is the second section%n</span><span class="delimiter">&quot;</span></span>)
    Section2 section2;

    <span class="directive">static</span> <span class="type">class</span> <span class="class">Section2</span> {
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Option X</span><span class="delimiter">&quot;</span></span>) <span class="type">int</span> x;
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-y</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Option Y</span><span class="delimiter">&quot;</span></span>) <span class="type">int</span> y;
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-z</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Option X</span><span class="delimiter">&quot;</span></span>) <span class="type">int</span> z;
    }

    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) {
        <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> OptionSectionDemo()).usage(<span class="predefined-type">System</span>.out);
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This prints the following usage help message:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: sectiondemo [-a=&lt;a&gt;] [-b=&lt;b&gt;] [-c=&lt;c&gt;] [-x=&lt;x&gt;] [-y=&lt;y&gt;] [-z=&lt;z&gt;]
Section demo
This is the first section
  -a=&lt;a&gt;    Option A
  -b=&lt;b&gt;    Option B
  -c=&lt;c&gt;    Option C
This is the second section
  -x=&lt;x&gt;    Option X
  -y=&lt;y&gt;    Option Y
  -z=&lt;z&gt;    Option X</pre>
</div>
</div>
<div class="paragraph">
<p>Note that the heading text must end with <code>%n</code> to insert a newline between the heading text and the first option.
This is for consistency with other headings in the usage help, like <code>@Command(headerHeading = "Usage:%n", optionListHeading = "%nOptions:%n")</code>.</p>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
Picocli will not initialize the <code>@ArgGroup</code>-annotated field
if none of the group options is specified on the command line.
For optional groups (groups with <code>multiplicity = "0..1"</code> - the default) this means that the <code>@ArgGroup</code>-annotated field may remain <code>null</code>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="_option_section_order">8.3.2. Option Section Order</h4>
<div class="paragraph">
<p>Options that are not in any argument group are always displayed before the option sections.</p>
</div>
<div class="paragraph">
<p>The ordering of option sections can be controlled with the <code>order</code> attribute. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@ArgGroup</span>(heading = <span class="string"><span class="delimiter">&quot;</span><span class="content">First%n</span><span class="delimiter">&quot;</span></span>, order = <span class="integer">1</span>) Section1 section1;
<span class="annotation">@ArgGroup</span>(heading = <span class="string"><span class="delimiter">&quot;</span><span class="content">Next%n</span><span class="delimiter">&quot;</span></span>,  order = <span class="integer">2</span>) Section2 section2;
<span class="annotation">@ArgGroup</span>(heading = <span class="string"><span class="delimiter">&quot;</span><span class="content">Last%n</span><span class="delimiter">&quot;</span></span>,  order = <span class="integer">3</span>) Section3 section3;</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_repeating_composite_argument_groups">8.4. Repeating Composite Argument Groups</h3>
<div class="paragraph">
<p>The below example shows how groups can be composed of other groups, and how arrays and collections can be used to capture repeating groups (with a <code>multiplicity</code> greater than one):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">repeating-composite-demo</span><span class="delimiter">&quot;</span></span>)
<span class="directive">public</span> <span class="type">class</span> <span class="class">CompositeGroupDemo</span> {

    <span class="annotation">@ArgGroup</span>(exclusive = <span class="predefined-constant">false</span>, multiplicity = <span class="string"><span class="delimiter">&quot;</span><span class="content">1..*</span><span class="delimiter">&quot;</span></span>)
    <span class="predefined-type">List</span>&lt;<span class="predefined-type">Composite</span>&gt; composites;

    <span class="directive">static</span> <span class="type">class</span> <span class="class">Composite</span> {
        <span class="annotation">@ArgGroup</span>(exclusive = <span class="predefined-constant">false</span>, multiplicity = <span class="string"><span class="delimiter">&quot;</span><span class="content">0..1</span><span class="delimiter">&quot;</span></span>)
        Dependent dependent;

        <span class="annotation">@ArgGroup</span>(exclusive = <span class="predefined-constant">true</span>, multiplicity = <span class="string"><span class="delimiter">&quot;</span><span class="content">1</span><span class="delimiter">&quot;</span></span>)
        Exclusive exclusive;
    }

    <span class="directive">static</span> <span class="type">class</span> <span class="class">Dependent</span> {
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-a</span><span class="delimiter">&quot;</span></span>, required = <span class="predefined-constant">true</span>) <span class="type">int</span> a;
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-b</span><span class="delimiter">&quot;</span></span>, required = <span class="predefined-constant">true</span>) <span class="type">int</span> b;
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-c</span><span class="delimiter">&quot;</span></span>, required = <span class="predefined-constant">true</span>) <span class="type">int</span> c;
    }

    <span class="directive">static</span> <span class="type">class</span> <span class="class">Exclusive</span> {
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>, required = <span class="predefined-constant">true</span>) <span class="type">boolean</span> x;
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-y</span><span class="delimiter">&quot;</span></span>, required = <span class="predefined-constant">true</span>) <span class="type">boolean</span> y;
        <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-z</span><span class="delimiter">&quot;</span></span>, required = <span class="predefined-constant">true</span>) <span class="type">boolean</span> z;
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the above example, the annotated <code>composites</code> field defines a composite group that must be specified at least once, and may be specified many times (<code>multiplicity = "1..*"</code>), on the command line. Notice that for multi-value groups the type of the <code>@ArgGroup</code>-annotated field must be a collection or an array to capture the multiple <code>Composite</code> instances that hold the values that were matched on the command line.</p>
</div>
<div class="paragraph">
<p>The synopsis of this command is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: repeating-composite-demo ([-a=&lt;a&gt; -b=&lt;b&gt; -c=&lt;c&gt;] (-x | -y | -z))...</pre>
</div>
</div>
<div class="paragraph">
<p>Each time the group is matched, picocli creates an instance of the <code>Composite</code> class and adds it to the <code>composites</code> list.</p>
</div>
<div class="paragraph">
<p>The <code>Composite</code> class itself contains two groups: an optional (<code>multiplicity = "0..1"</code>) group of dependent options that must co-occur, and another group of mutually exclusive options, which is mandatory (<code>multiplicity = "1"</code>).</p>
</div>
<div class="paragraph">
<p>The below example illustrates:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">CompositeGroupDemo example = <span class="keyword">new</span> CompositeGroupDemo();
CommandLine cmd = <span class="keyword">new</span> CommandLine(example);

cmd.parseArgs(<span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">-a=1</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">-b=1</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">-c=1</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">-a=2</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">-b=2</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">-c=2</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">-y</span><span class="delimiter">&quot;</span></span>);
<span class="keyword">assert</span> example.composites.size() == <span class="integer">2</span>;

<span class="predefined-type">Composite</span> c1 = example.composites.get(<span class="integer">0</span>);
<span class="keyword">assert</span> c1.exclusive.x;
<span class="keyword">assert</span> c1.dependent.a == <span class="integer">1</span>;
<span class="keyword">assert</span> c1.dependent.b == <span class="integer">1</span>;
<span class="keyword">assert</span> c1.dependent.c == <span class="integer">1</span>;

<span class="predefined-type">Composite</span> c2 = example.composites.get(<span class="integer">1</span>);
<span class="keyword">assert</span> c2.exclusive.y;
<span class="keyword">assert</span> c2.dependent.a == <span class="integer">2</span>;
<span class="keyword">assert</span> c2.dependent.b == <span class="integer">2</span>;
<span class="keyword">assert</span> c2.dependent.c == <span class="integer">2</span>;</code></pre>
</div>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Picocli will not initialize the <code>@ArgGroup</code>-annotated field
if none of the group options is specified on the command line.
For optional groups (groups with <code>multiplicity = "0..1"</code> - the default) this means that the <code>@ArgGroup</code>-annotated field may remain <code>null</code>.
If the application assigned a non-<code>null</code> Collection in the field declaration (e.g., <code>@ArgGroup List&lt;Composite&gt; composites = new ArrayList&lt;&gt;();</code>), then the collection will remain empty if none of the group options is specified on the command line.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_default_values_in_argument_groups">8.5. Default Values in Argument Groups</h3>
<div class="paragraph">
<p>The <a href="#_default_values">default values</a> of options in an argument group are applied when at least one option in the group is matched on the command line and picocli instantiates the user object of the group.</p>
</div>
<div class="paragraph">
<p>Picocli will not initialize the <code>@ArgGroup</code>-annotated field (and so no default values are applied) if none of the group options is specified on the command line.</p>
</div>
<div class="sect3">
<h4 id="_default_values_in_group_usage_help">8.5.1. Default Values in Group Usage Help</h4>
<div class="paragraph">
<p>When options are used in argument groups, they can only define default values via the <code>@Option(defaultValue = "&#8230;&#8203;")</code> annotation (not in the field declaration).</p>
</div>
<div class="paragraph">
<p>When defined this way, the <code>${DEFAULT-VALUE}</code> variable can be used to <a href="#_show_default_values">show the default value</a> in the description of options in an argument group. For example:</p>
</div>
<div class="listingblock">
<div class="title">This works correctly: usage help will show the default value.</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">GoodGroup</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>, defaultValue = <span class="string"><span class="delimiter">&quot;</span><span class="content">123</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Default: ${DEFAULT-VALUE}</span><span class="delimiter">&quot;</span></span>)
    <span class="type">int</span> x;
}
<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">good</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">usage help shows the default value</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">GoodExample</span> {
    <span class="annotation">@ArgGroup</span> GoodGroup goodGroup;

    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) {
        <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> GoodExample()).usage(<span class="predefined-type">System</span>.out);
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>When the default value is defined in the annotation, the usage help shows the correct default value:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: good [[-x=&lt;x&gt;]]
usage help shows the default value
  -x=&lt;x&gt;    Default: 123</pre>
</div>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Picocli will not be able to retrieve the default values that are defined by assigning a value in the declaration of an <code>@Option</code>-annotated field in a group. For example:</p>
</div>
<div class="listingblock">
<div class="title">This does not work correctly: usage help shows <code>null</code> as the default value.</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">BadGroup</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Default: ${DEFAULT-VALUE}</span><span class="delimiter">&quot;</span></span>)
    <span class="type">int</span> x = <span class="integer">123</span>; <span class="comment">// picocli cannot find this value until `BadGroup` is instantiated</span>
}
<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">bad</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">usage help shows the wrong default value</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">BadExample</span> {
    <span class="annotation">@ArgGroup</span> BadGroup badGroup;

    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) {
        <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> BadExample()).usage(<span class="predefined-type">System</span>.out);
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>When the default value is defined in the field declaration and not in the annotation, usage help for the options in the group incorrectly shows <code>null</code> as the default value:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: bad [[-x=&lt;x&gt;]]
usage help shows the wrong default value
  -x=&lt;x&gt;    Default: null</pre>
</div>
</div>
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_positional_parameters_2">8.6. Positional Parameters</h3>
<div class="paragraph">
<p>When a <code>@Parameters</code> positional parameter is part of a group, its <code>index</code> is the index <em>within the group</em>, not within the command.</p>
</div>
</div>
<div class="sect2">
<h3 id="_argument_group_limitations">8.7. Argument Group Limitations</h3>
<div class="ulist">
<ul>
<li>
<p>Options with the same name cannot be defined in multiple groups. Similarly, it is not possible to define an option outside of a group with the same name as a different option that is part of a group.</p>
</li>
<li>
<p>Positional parameters in a single group work fine, but take care (or avoid) defining positional parameters in multiple groups or positional parameters in a group as well as outside a group. Positional parameters are matched by index, and while the index of a group is reset when a new group multiple is encountered, the index of positional parameters outside a group only increases and is never reset.</p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="execute">9. Executing Commands</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Parsing the command line arguments is the first step. A robust real-world application needs to handle a number of scenarios:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>User input was invalid</p>
</li>
<li>
<p>User requested usage help (potentially for a subcommand)</p>
</li>
<li>
<p>User requested version help (potentially for a subcommand)</p>
</li>
<li>
<p>None of the above: we can run the business logic (potentially for a subcommand)</p>
</li>
<li>
<p>The business logic may throw an exception</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Picocli 4.0 introduces an <code>execute</code> method for handling all of the above scenarios in a single line of code. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MyApp()).execute(args);</code></pre>
</div>
</div>
<div class="paragraph">
<p>With the <code>execute</code> method, application code can be <strong>extremely compact</strong>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><table class="CodeRay"><tr>
  <td class="line-numbers"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
</pre></td>
  <td class="code"><pre><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">myapp</span><span class="delimiter">&quot;</span></span>, mixinStandardHelpOptions = <span class="predefined-constant">true</span>, version = <span class="string"><span class="delimiter">&quot;</span><span class="content">1.0</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">MyApp</span> <span class="directive">implements</span> <span class="predefined-type">Callable</span>&lt;<span class="predefined-type">Integer</span>&gt; {

    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>) <span class="type">int</span> x;

    <span class="annotation">@Override</span>
    <span class="directive">public</span> <span class="predefined-type">Integer</span> call() { <span class="comment">// business logic</span>
        <span class="predefined-type">System</span>.out.printf(<span class="string"><span class="delimiter">&quot;</span><span class="content">x=%s%n</span><span class="delimiter">&quot;</span></span>, x);
        <span class="keyword">return</span> <span class="integer">123</span>; <span class="comment">// exit code</span>
    }

    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span>... args) { <span class="comment">// bootstrap the application</span>
        <span class="predefined-type">System</span>.exit(<span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MyApp()).execute(args));
    }
}</pre></td>
</tr></table></code></pre>
</div>
</div>
<div class="paragraph">
<p>Despite being only 15 lines long, this is a full-fledged application, with <a href="#_mixin_standard_help_options"><code>--help</code> and <code>--version</code></a> options in addition to the <code>-x</code> option.
The <code>execute</code> method will show the usage help or version information if requested by the user, and invalid user input will result
in a helpful <a href="#_handling_errors">error message</a>. If the user input was valid, the business logic is invoked.
Finally, the <code>execute</code> method returns an <a href="#_exit_code">exit status code</a> that can be used to call <code>System.exit</code> if desired.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
A command is executable if its user object implements <code>Runnable</code> or <code>Callable</code>, or is a <code>@Command</code>-annotated <code>Method</code>. Examples follow below.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The <code>execute</code> method replaces the older <code>run</code>, <code>call</code>, <code>invoke</code> and <code>parseWithHandlers</code> methods.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The <a href="#_diy_command_execution">DIY Command Execution</a> section shows an example of the boilerplate code that can be omitted with the <code>execute</code> method.</p>
</div>
<div class="sect2">
<h3 id="_exit_code">9.1. Exit Code</h3>
<div class="paragraph">
<p>Many command line applications return an <a href="https://en.wikipedia.org/wiki/Exit_status">exit code</a> to signify success or failure. Zero often means success, a non-zero exit code is often used for errors, but other than that, meanings differ per application.</p>
</div>
<div class="paragraph">
<p>The <code>CommandLine.execute</code> method introduced in picocli 4.0 returns an <code>int</code>, and applications can use this return value to call <code>System.exit</code> if desired. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span>... args) {
  <span class="type">int</span> exitCode = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MyApp()).execute(args);
  <span class="predefined-type">System</span>.exit(exitCode);
}</code></pre>
</div>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
Older versions of picocli had some limited exit code support where picocli would call <code>System.exit</code>, but this is now deprecated.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_generating_an_exit_code">9.2. Generating an Exit Code</h3>
<div class="paragraph">
<p><code>@Command</code>-annotated classes that implement <code>Callable</code> and <code>@Command</code>-<a href="#command-methods">annotated methods</a> can simply return an <code>int</code> or <code>Integer</code>, and this value will be returned from <code>CommandLine.execute</code>. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">greet</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">Greet</span> <span class="directive">implements</span> <span class="predefined-type">Callable</span>&lt;<span class="predefined-type">Integer</span>&gt; {
    <span class="directive">public</span> <span class="predefined-type">Integer</span> call() {
        <span class="predefined-type">System</span>.out.println(<span class="string"><span class="delimiter">&quot;</span><span class="content">hi</span><span class="delimiter">&quot;</span></span>);
        <span class="keyword">return</span> <span class="integer">1</span>;
    }

    <span class="comment">// define a &quot;shout&quot; subcommand with a @Command-annotated method</span>
    <span class="annotation">@Command</span>
    <span class="type">int</span> shout() {
        <span class="predefined-type">System</span>.out.println(<span class="string"><span class="delimiter">&quot;</span><span class="content">HI!</span><span class="delimiter">&quot;</span></span>);
        <span class="keyword">return</span> <span class="integer">2</span>;
    }
}

<span class="keyword">assert</span> <span class="integer">1</span> == <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> Greet()).execute();
<span class="keyword">assert</span> <span class="integer">2</span> == <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> Greet()).execute(<span class="string"><span class="delimiter">&quot;</span><span class="content">shout</span><span class="delimiter">&quot;</span></span>);</code></pre>
</div>
</div>
<div class="paragraph">
<p>Commands with a user object that implements <code>Runnable</code> can implement the <code>IExitCodeGenerator</code> interface to generate an exit code. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">wave</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">Gesture</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span>, IExitCodeGenerator {

    <span class="annotation">@Override</span> <span class="directive">public</span> <span class="type">void</span> run() {
        <span class="predefined-type">System</span>.out.println(<span class="string"><span class="delimiter">&quot;</span><span class="content">wave</span><span class="delimiter">&quot;</span></span>);
    }

    <span class="annotation">@Override</span> <span class="directive">public</span> <span class="type">int</span> getExitCode() {
        <span class="keyword">return</span> <span class="integer">3</span>;
    }
}

<span class="keyword">assert</span> <span class="integer">3</span> == <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> Gesture()).execute();</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_exception_exit_codes">9.3. Exception Exit Codes</h3>
<div class="paragraph">
<p>By default, the <code>execute</code> method returns <code>CommandLine.ExitCode.OK</code> (<code>0</code>) on success, <code>CommandLine.ExitCode.SOFTWARE</code> (<code>1</code>) when an exception occurred in the Runnable, Callable or command method, and <code>CommandLine.ExitCode.USAGE</code> (<code>2</code>) for invalid input. (These are common values according to <a href="https://stackoverflow.com/questions/1101957/are-there-any-standard-exit-status-codes-in-linux/40484670#40484670">this StackOverflow answer</a>). This can be customized with the <code>@Command</code> annotation. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(exitCodeOnInvalidInput = <span class="integer">123</span>,
   exitCodeOnExecutionException = <span class="integer">456</span>)</code></pre>
</div>
</div>
<div class="paragraph">
<p>Additionally, applications can configure a <code>IExitCodeExceptionMapper</code> to map a specific exception to an exit code:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">MyMapper</span> <span class="directive">implements</span> IExitCodeExceptionMapper {
    <span class="annotation">@Override</span>
    <span class="directive">public</span> <span class="type">int</span> getExitCode(<span class="predefined-type">Throwable</span> t) {
        <span class="keyword">if</span> (t <span class="keyword">instanceof</span> <span class="exception">FileNotFoundException</span>) {
            <span class="keyword">return</span> <span class="integer">74</span>;
        }
        <span class="keyword">return</span> <span class="integer">1</span>;
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>When the end user specified invalid input, the <code>execute</code> method prints an error message followed by the usage help message of the command, and returns an exit code. This can be <a href="#_invalid_user_input">customized</a> by configuring a <code>IParameterExceptionHandler</code>.</p>
</div>
<div class="paragraph">
<p>If the business logic of the command throws an exception, the <code>execute</code> method prints the stack trace of the exception and returns an exit code. This can be customized by configuring a <code>IExecutionExceptionHandler</code>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_usage_help_exit_code_section">9.4. Usage Help Exit Code Section</h3>
<div class="paragraph">
<p>By default, the usage help message does not include exit code information.
Applications that call <code>System.exit</code> need to configure the usage help message to show exit code details,
either with the <code>exitCodeListHeading</code> and <code>exitCodeList</code> annotation attributes,
or programmatically by calling <code>UsageMessageSpec.exitCodeListHeading</code> and <code>UsageMessageSpec.exitCodeList</code>.</p>
</div>
<div class="paragraph">
<p>See <a href="#_exit_code_list">Exit Code List</a> for details.</p>
</div>
</div>
<div class="sect2">
<h3 id="_execution_configuration">9.5. Execution Configuration</h3>
<div class="paragraph">
<p>The following methods can be used to configure the behaviour of the <code>execute</code> method:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>get/setOut</p>
</li>
<li>
<p>get/setErr</p>
</li>
<li>
<p>get/setColorScheme</p>
</li>
<li>
<p>get/setExecutionStrategy</p>
</li>
<li>
<p>get/setParameterExceptionHandler</p>
</li>
<li>
<p>get/setExecutionExceptionHandler</p>
</li>
<li>
<p>get/setExitCodeExceptionMapper</p>
</li>
</ul>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
The above methods are not applicable with (and ignored by) other entry points like <code>parse</code>, <code>parseArgs</code>, <code>populateCommand</code>, <code>run</code>, <code>call</code>, <code>invoke</code>, <code>parseWithHandler</code> and <code>parseWithHandlers</code>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_migration">9.6. Migration</h3>
<div class="paragraph">
<p>Older versions of picocli supported <code>run</code>, <code>call</code>, <code>invoke</code> and <code>parseWithHandlers</code> convenience methods that were similar to <code>execute</code> but had limited support for parser configuration and and limited support for exit codes.
These methods are deprecated from picocli 4.0.
The sections below show some common usages and how the same can be achieved with the <code>execute</code> API.</p>
</div>
<div class="sect3">
<h4 id="_customizing_output_streams_and_ansi_settings">9.6.1. Customizing Output Streams and ANSI settings</h4>
<div class="listingblock">
<div class="title">Before:</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">PrintStream</span> out = <span class="comment">// output stream for user-requested help</span>
<span class="predefined-type">PrintStream</span> err = <span class="comment">// output stream for error messages</span>
Ansi ansi = <span class="comment">// to use ANSI colors and styles or not</span>
CommandLine.run(<span class="keyword">new</span> MyRunnable(), out, err, ansi, args);</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">After:</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">PrintWriter</span> out = <span class="comment">// output stream for user-requested help</span>
<span class="predefined-type">PrintWriter</span> err = <span class="comment">// output stream for error messages</span>
Ansi ansi = <span class="comment">// to use ANSI colors and styles or not</span>

CommandLine cmd = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MyRunnable())
        .setOut(out);
        .setErr(err);
        .setColorScheme(Help.defaultColorScheme(ansi));

<span class="type">int</span> exitCode = cmd.execute(args);</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_return_value_from_callable_or_method">9.6.2. Return Value from Callable or Method</h4>
<div class="listingblock">
<div class="title">Before:</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">MyCallable</span> <span class="directive">implements</span> <span class="predefined-type">Callable</span>&lt;MyResult&gt; {
    <span class="directive">public</span> MyResult call() { ... }
}

MyResult result = CommandLine.call(<span class="keyword">new</span> MyCallable(), args);</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">After:</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">CommandLine cmd = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MyCallable());
<span class="type">int</span> exitCode = cmd.execute(args);
MyResult result = cmd.getExecutionResult();</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_invoking_command_methods">9.6.3. Invoking Command Methods</h4>
<div class="listingblock">
<div class="title">Before:</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">MyCommand</span> {
    <span class="annotation">@Command</span>
    <span class="directive">public</span> MyResult doit(<span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>) <span class="type">int</span> x) { ... }
}

MyResult result = CommandLine.invoke(<span class="string"><span class="delimiter">&quot;</span><span class="content">doit</span><span class="delimiter">&quot;</span></span>, MyCommand.class, args);</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">After:</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">Method</span> doit = CommandLine.getCommandMethods(MyCommand.class, <span class="string"><span class="delimiter">&quot;</span><span class="content">doit</span><span class="delimiter">&quot;</span></span>).get(<span class="integer">0</span>);
CommandLine cmd = <span class="keyword">new</span> CommandLine(doit);
<span class="type">int</span> exitCode = cmd.execute(args);
MyResult result = cmd.getExecutionResult();</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_executing_commands_with_subcommands">9.6.4. Executing Commands with Subcommands</h4>
<div class="paragraph">
<p>The <code>IParseResultHandler2</code> interface has been deprecated in picocli 4.0 in favor of <code>IExecutionStrategy</code>. The existing built-in handlers <code>RunLast</code>, <code>RunAll</code> and <code>RunFirst</code> implement the <code>IExecutionStrategy</code> interface and can still be used:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>the <code>RunLast</code> handler prints help if requested, and otherwise gets the <em>last specified</em> command or subcommand and tries to execute it as a <code>Runnable</code>, <code>Callable</code> or <code>Method</code>. This is the default execution strategy.</p>
</li>
<li>
<p>the <code>RunFirst</code> handler prints help if requested, and otherwise executes the <em>top-level</em> command as a <code>Runnable</code>, <code>Callable</code> or <code>Method</code></p>
</li>
<li>
<p>the <code>RunAll</code> handler prints help if requested, and otherwise executes <em>all</em> commands and subcommands that the user specified on the command line as <code>Runnable</code>, <code>Callable</code> or <code>Method</code> tasks</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="title">Before</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">CommandLine cmd = <span class="keyword">new</span> CommandLine(MyTopLevelCommand())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">status</span><span class="delimiter">&quot;</span></span>,   <span class="keyword">new</span> GitStatus())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">commit</span><span class="delimiter">&quot;</span></span>,   <span class="keyword">new</span> GitCommit())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">add</span><span class="delimiter">&quot;</span></span>,      <span class="keyword">new</span> GitAdd());
<span class="predefined-type">List</span>&lt;<span class="predefined-type">Object</span>&gt; result = cmd.parseWithHandler(<span class="keyword">new</span> RunAll(), args);</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">After</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">CommandLine cmd = <span class="keyword">new</span> CommandLine(MyTopLevelCommand())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">status</span><span class="delimiter">&quot;</span></span>,   <span class="keyword">new</span> GitStatus())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">commit</span><span class="delimiter">&quot;</span></span>,   <span class="keyword">new</span> GitCommit())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">add</span><span class="delimiter">&quot;</span></span>,      <span class="keyword">new</span> GitAdd());

<span class="comment">// the default is RunLast, this can be customized:</span>
cmd.setExecutionStrategy(<span class="keyword">new</span> RunAll());
<span class="type">int</span> exitCode = cmd.execute(args);</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>ParseResult</code> can be used to get the return value from a Callable or Method subcommand:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="comment">// getting return value from Callable or Method command</span>
<span class="predefined-type">Object</span> topResult = cmd.getExecutionResult();

<span class="comment">// getting return value from Callable or Method subcommand</span>
ParseResult parseResult = cmd.getParseResult();
<span class="keyword">if</span> (parseResult.subcommand() != <span class="predefined-constant">null</span>) {
    CommandLine sub = parseResult.subcommand().commandSpec().commandLine();
    <span class="predefined-type">Object</span> subResult = sub.getExecutionResult();
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_diy_command_execution">9.7. DIY Command Execution</h3>
<div class="paragraph">
<p>Alternatively, applications may want to use the <code>parseArgs</code> method directly and write their own "Do It Yourself" command execution logic.</p>
</div>
<div class="paragraph">
<p>The example below covers the following common scenarios:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Handle invalid user input, and report any problems to the user (potentially suggesting alternative options and subcommands for simple typos if we want to get fancy).</p>
</li>
<li>
<p>Check if the user requested usage help, and print this help and abort processing if this was the case.</p>
</li>
<li>
<p>Check if the user requested version information, and print this information and abort processing if this was the case.</p>
</li>
<li>
<p>If none of the above, run the business logic of the application.</p>
</li>
<li>
<p>Handle any errors that occurred in the business logic.</p>
</li>
</ol>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">Callable</span>&lt;<span class="predefined-type">Object</span>&gt; callable = <span class="keyword">new</span> MyCallable();
CommandLine cmd = <span class="keyword">new</span> CommandLine(callable);
<span class="keyword">try</span> {
    ParseResult parseResult = cmd.parseArgs(args);

    <span class="comment">// Did user request usage help (--help)?</span>
    <span class="keyword">if</span> (cmd.isUsageHelpRequested()) {
        cmd.usage(cmd.getOut());
        <span class="keyword">return</span> cmd.getCommandSpec().exitCodeOnUsageHelp();

    <span class="comment">// Did user request version help (--version)?</span>
    } <span class="keyword">else</span> <span class="keyword">if</span> (cmd.isVersionHelpRequested()) {
        cmd.printVersionHelp(cmd.getOut());
        <span class="keyword">return</span> cmd.getCommandSpec().exitCodeOnVersionHelp();
    }
    <span class="comment">// invoke the business logic</span>
    <span class="predefined-type">Object</span> result = callable.call();
    cmd.setExecutionResult(result);
    <span class="keyword">return</span> cmd.getCommandSpec().exitCodeOnSuccess();

<span class="comment">// invalid user input: print error message and usage help</span>
} <span class="keyword">catch</span> (ParameterException ex) {
    cmd.getErr().println(ex.getMessage());
    <span class="keyword">if</span> (!UnmatchedArgumentException.printSuggestions(ex, cmd.getErr())) {
        ex.getCommandLine().usage(cmd.getErr());
    }
    <span class="keyword">return</span> cmd.getCommandSpec().exitCodeOnInvalidInput();

<span class="comment">// exception occurred in business logic</span>
} <span class="keyword">catch</span> (<span class="exception">Exception</span> ex) {
    ex.printStackTrace(cmd.getErr());
    <span class="keyword">return</span> cmd.getCommandSpec().exitCodeOnExecutionException();
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>CommandLine.execute</code> method is equivalent to the above, and additionally handles subcommands correctly.</p>
</div>
</div>
<div class="sect2">
<h3 id="_handling_errors">9.8. Handling Errors</h3>
<div class="paragraph">
<p>Internally, the <code>execute</code> method parses the specified user input and populates the options and positional parameters defined by the annotations.
When the user specified invalid input, this is handled by the <code>IParameterExceptionHandler</code>.</p>
</div>
<div class="paragraph">
<p>After parsing the user input, the business logic of the command is invoked: the <code>run</code>, <code>call</code> or <code>@Command</code>-annotated method.
When an exception is thrown by the business logic, this is handled by the <code>IExecutionExceptionHandler</code>.</p>
</div>
<div class="paragraph">
<p>In most cases, the default handlers are sufficient, but the sections below show how they can be customized.</p>
</div>
<div class="sect3">
<h4 id="_invalid_user_input">9.8.1. Invalid User Input</h4>
<div class="paragraph">
<p>When the user specified invalid input, the parser throws a <code>ParameterException</code>.
In the <code>execute</code> method, such exceptions are caught and passed to the <code>IParameterExceptionHandler</code>.</p>
</div>
<div class="paragraph">
<p>The default parameter exception handler prints an error message describing the problem,
followed by either <a href="https://picocli.info/apidocs/picocli/CommandLine.UnmatchedArgumentException.html#printSuggestions-picocli.CommandLine.ParameterException-java.io.PrintWriter-">suggested alternatives</a>
for mistyped options, or the full usage help message of the problematic command.
Finally, the handler returns an <a href="#_exception_exit_codes">exit code</a>.
This is sufficient for most applications.</p>
</div>
<div class="paragraph">
<p>Sometimes you want to display a shorter message. For example, the <code>grep</code> utility does not not show the full usage help when it gets an invalid argument:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>$ grep -d recurese "ERROR" logs/*

Error: invalid argument ‘recurese’ for ‘--directories’
Valid arguments are:
  - ‘read’
  - ‘recurse’
  - ‘skip’
Usage: grep [OPTION]... PATTERN [FILE]...
Try 'grep --help' for more information.</pre>
</div>
</div>
<div class="paragraph">
<p>You can customize how your application handles invalid user input by setting a custom <code>IParameterExceptionHandler</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MyApp())
    .setParameterExceptionHandler(<span class="keyword">new</span> ShortErrorMessageHandler())
    .execute(args);</code></pre>
</div>
</div>
<div class="paragraph">
<p>Where the <code>IParameterExceptionHandler</code> implementation could be something like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">ShortErrorMessageHandler</span> <span class="directive">implements</span> IParameterExceptionHandler {

    <span class="directive">public</span> <span class="type">int</span> handleParseException(ParameterException ex, <span class="predefined-type">String</span><span class="type">[]</span> args) {
        CommandLine cmd = ex.getCommandLine();
        <span class="predefined-type">PrintWriter</span> writer = cmd.getErr();

        writer.println(ex.getMessage());
        UnmatchedArgumentException.printSuggestions(ex, writer);
        writer.print(cmd.getHelp().fullSynopsis()); <span class="comment">// since 4.1</span>

        CommandSpec spec = cmd.getCommandSpec();
        writer.printf(<span class="string"><span class="delimiter">&quot;</span><span class="content">Try '%s --help' for more information.%n</span><span class="delimiter">&quot;</span></span>, spec.qualifiedName());

        <span class="keyword">return</span> cmd.getExitCodeExceptionMapper() != <span class="predefined-constant">null</span>
                    ? cmd.getExitCodeExceptionMapper().getExitCode(ex)
                    : spec.exitCodeOnInvalidInput();
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_business_logic_exceptions">9.8.2. Business Logic Exceptions</h4>
<div class="paragraph">
<p>When the business logic throws an exception, this exception is caught and passed to the <code>IExecutionExceptionHandler</code>.</p>
</div>
<div class="paragraph">
<p>The default execution exception handling results in the stack trace of the exception being printed and an <a href="#_exception_exit_codes">exit code</a> being returned.
This is sufficient for most applications.</p>
</div>
<div class="paragraph">
<p>If you have designed your business logic to throw exceptions with user-facing error messages, you want to print this error message instead of the stack trace.
This can be accomplished by installing a custom <code>IExecutionExceptionHandler</code>, like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MyApp())
    .setExecutionExceptionHandler(<span class="keyword">new</span> PrintExceptionMessageHandler())
    .execute(args);</code></pre>
</div>
</div>
<div class="paragraph">
<p>Where the <code>IExecutionExceptionHandler</code> implementation could look something like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">PrintExceptionMessageHandler</span> <span class="directive">implements</span> IExecutionExceptionHandler() {
    <span class="directive">public</span> <span class="type">int</span> handleExecutionException(<span class="exception">Exception</span> ex,
                                        CommandLine commandLine,
                                        ParseResult parseResult) {

        commandLine.getErr().println(ex.getMessage());

        <span class="keyword">return</span> cmd.getExitCodeExceptionMapper() != <span class="predefined-constant">null</span>
                    ? cmd.getExitCodeExceptionMapper().getExitCode(ex)
                    : cmd.getCommandSpec().exitCodeOnExecutionException();
    }
}</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_parser_configuration">10. Parser Configuration</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_overwriting_single_options">10.1. Overwriting Single Options</h3>
<div class="paragraph">
<p>When a single-value option is specified multiple times on the command line, the default parser behaviour is
to throw an <code>OverwrittenOptionException</code>. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Option</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">-p</span><span class="delimiter">&quot;</span></span>) <span class="type">int</span> port;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The following input results in an <code>OverwrittenOptionException</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>&lt;command&gt; -p 80 -p 8080</pre>
</div>
</div>
<div class="paragraph">
<p>Applications can change this by calling <code>CommandLine.setOverwrittenOptionsAllowed(true)</code> before parsing the input.
When overwritten options are allowed, the last specified value takes effect (the above input will set the <code>port</code> field to <code>8080</code>)
and a WARN level message is printed to the console. (See <a href="#_tracing">Tracing</a> for how to switch off the warnings.)</p>
</div>
</div>
<div class="sect2">
<h3 id="_stop_at_positional">10.2. Stop At Positional</h3>
<div class="paragraph">
<p>By default, positional parameters can be mixed with options on the command line, but this is not always desirable.
From picocli 2.3, applications can call <code>CommandLine.setStopAtPositional(true)</code>
to force the parser to treat all values following the first positional parameter as positional parameters.</p>
</div>
<div class="paragraph">
<p>When this flag is set, the first positional parameter effectively serves as an "<a href="#_double_dash">end of options</a>" marker.</p>
</div>
</div>
<div class="sect2">
<h3 id="_unmatched_input">10.3. Unmatched Input</h3>
<div class="paragraph">
<p>By default, an <code>UnmatchedArgumentException</code> is thrown when a command line argument cannot be assigned to
an option or positional parameter. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">OnlyThree</span> {
    <span class="annotation">@Parameters</span>(arity = <span class="string"><span class="delimiter">&quot;</span><span class="content">3</span><span class="delimiter">&quot;</span></span>) <span class="predefined-type">String</span><span class="type">[]</span> values;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The command has only one annotated field, <code>values</code>, and it expects exactly three arguments,
so the following input results in an <code>UnmatchedArgumentException</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>java OnlyThree 1 2 3 4 5</pre>
</div>
</div>
<div class="paragraph">
<p>Applications can change this by calling <code>CommandLine.setUnmatchedArgumentsAllowed(true)</code> before parsing the input.
When unmatched arguments are allowed, the above input will be accepted and a WARN level message is printed to the console.
(See <a href="#_tracing">Tracing</a> for how to switch off the warnings.)</p>
</div>
<div class="paragraph">
<p>The unmatched argument values can be obtained with the <code>CommandLine.getUnmatchedArguments()</code> method.</p>
</div>
</div>
<div class="sect2">
<h3 id="unmatched-annotation">10.4. <code>@Unmatched</code> annotation</h3>
<div class="paragraph">
<p>From picocli 3.0, fields annotated with <code>@Unmatched</code> will be populated with the unmatched arguments.
The field must be of type <code>String[]</code> or <code>List&lt;String&gt;</code>.</p>
</div>
<div class="paragraph">
<p>If picocli finds a field annotated with <code>@Unmatched</code>, it automatically sets <code>unmatchedArgumentsAllowed</code> to <code>true</code>
so no <code>UnmatchedArgumentException</code> is thrown when a command line argument cannot be assigned to an option or positional parameter.
If no unmatched arguments are found, the value of the field annotated with <code>@Unmatched</code> is unchanged.</p>
</div>
</div>
<div class="sect2">
<h3 id="_unknown_options">10.5. Unknown Options</h3>
<div class="paragraph">
<p>A special case of unmatched input are arguments that resemble options but don&#8217;t match any of the defined options.
For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-a</span><span class="delimiter">&quot;</span></span>) <span class="predefined-type">String</span> alpha;
<span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-b</span><span class="delimiter">&quot;</span></span>) <span class="predefined-type">String</span> beta;
<span class="annotation">@Parameters</span> <span class="predefined-type">String</span><span class="type">[]</span> remainder;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above defines options <code>-a</code> and <code>-b</code>, but what should the parser do with input like this?</p>
</div>
<div class="listingblock">
<div class="content">
<pre>&lt;command&gt; -x -a AAA</pre>
</div>
</div>
<div class="paragraph">
<p>The <code>-x</code> argument "looks like" an option but there is no <code>-x</code> option defined&#8230;&#8203;</p>
</div>
<div class="paragraph">
<p>One possibility is to silently accept such values as positional parameters but this is often not desirable.
From version 1.0, picocli determines if the unmatched argument "resembles an option"
by comparing its leading characters to the prefix characters of the known options.</p>
</div>
<div class="paragraph">
<p>When the unmatched value is similar to the known options, picocli throws an <code>UnmatchedArgumentException</code>
rather than treating it as a positional parameter.</p>
</div>
<div class="paragraph">
<p>As usual, <code>CommandLine.setUnmatchedArgumentsAllowed(true)</code> will accept unmatched input and
display a WARN-level message on the console.</p>
</div>
<div class="paragraph">
<p>Arguments that are not considered similar to the known options are interpreted as positional parameters:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>&lt;command&gt; x -a AAA</pre>
</div>
</div>
<div class="paragraph">
<p>The above input is treated by the parser as one positional parameter (<code>x</code>) followed by the <code>-a</code> option and its value.</p>
</div>
<div class="paragraph">
<p>Picocli 3.0 introduced a <code>CommandLine.setUnmatchedOptionsArePositionalParams(boolean)</code> method that can be used to
force the parser to treat arguments resembling an option as positional parameters. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>&lt;command&gt; -x -a AAA</pre>
</div>
</div>
<div class="paragraph">
<p>When <code>unmatchedOptionsArePositionalParams</code> is set to <code>true</code>, the unknown option <code>-x</code> is treated as a positional parameter.
The next argument <code>-a</code> is recognized and processed as a known option like you would expect.</p>
</div>
</div>
<div class="sect2">
<h3 id="_stop_at_unmatched">10.6. Stop At Unmatched</h3>
<div class="paragraph">
<p>From picocli 2.3, applications can call <code>CommandLine.setStopAtUnmatched(true)</code> to force the parser to stop interpreting
options and positional parameters as soon as it encounters an unmatched argument.</p>
</div>
<div class="paragraph">
<p>When this flag is set, the first unmatched argument and all subsequent command line arguments are added to the
unmatched arguments list returned by <code>CommandLine.getUnmatchedArguments()</code>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_toggle_boolean_flags">10.7. Toggle Boolean Flags</h3>
<div class="paragraph">
<p>When a flag option is specified on the command line picocli will set its value to the opposite of its <em>default</em> value.</p>
</div>
<div class="paragraph">
<p>Prior to 4.0, the default was to "toggle" boolean flags to the opposite of their <em>current</em> value:
if the previous value was <code>true</code> it is set to <code>false</code>, and when the value was <code>false</code> it is set to <code>true</code>.</p>
</div>
<div class="paragraph">
<p>Applications can call <code>CommandLine.setToggleBooleanFlags(true)</code> to enable toggling.
Note that when toggling is enabled, specifying a flag option twice on the command line will have no effect because they cancel each other out.</p>
</div>
</div>
<div class="sect2">
<h3 id="_posix_clustered_short_options">10.8. POSIX Clustered Short Options</h3>
<div class="paragraph">
<p>By default, the picocli parser allows POSIX clustered short options, so short options like <code>-x -v -f SomeFile</code> can be clustered together like <code>-xvfSomeFile</code>.
From picocli 3.0, applications can call <code>CommandLine.setPosixClusteredShortOptionsAllowed(false)</code> to enforce that options must be separated with whitespace on the command line.
(This also means that option parameters must be separated from the option name by whitespace or the <code>=</code> <a href="#_option_parameter_separators">separator</a> character, so <code>-D key=value</code> and <code>-D=key=value</code> will be recognized but <code>-Dkey=value</code> will not.)</p>
</div>
</div>
<div class="sect2">
<h3 id="_lenient_mode_incubating">10.9. Lenient Mode (Incubating)</h3>
<div class="paragraph">
<p>From picocli 3.2, the parser can be configured to continue parsing invalid input to the end.
When <code>collectErrors</code> is set to <code>true</code>, and a problem occurs during parsing, an <code>Exception</code> is added to the <code>ParseResult.errors()</code> list and parsing continues. The default behaviour (when <code>collectErrors</code> is <code>false</code>) is to abort parsing by throwing the <code>Exception</code>.</p>
</div>
<div class="paragraph">
<p>This is useful when generating completion candidates on partial input, and is also useful when using picocli in
languages like Clojure where idiomatic error handling does not involve throwing and catching exceptions.</p>
</div>
<div class="paragraph">
<p>When using this feature, applications are responsible for actively verifying that no errors occurred before executing the business logic. Use with care!</p>
</div>
</div>
<div class="sect2">
<h3 id="_quoted_values">10.10. Quoted Values</h3>
<div class="sect3">
<h4 id="_trimming_quotes">10.10.1. Trimming Quotes</h4>
<div class="paragraph">
<p>From picocli 3.7, quotes around command line parameters are preserved by default (previously they were removed). This can be configured with <code>CommandLine::setTrimQuotes</code>, or the parser configuration <code>trimQuotes</code>. From picocli 4.0, quoted arguments can contain nested quoted substrings, to give end users fine-grained control over how values are split.</p>
</div>
<div class="paragraph">
<p>If <code>CommandLine::setTrimQuotes</code>, or the parser configuration <code>trimQuotes</code> is set to <code>true</code>, picocli will remove quotes from the command line arguments, as follows:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>As each command line argument is processed, the below <a href="#_smart_unquote">smart unquote</a> procedure is used to trim the outermost quotes.</p>
</li>
<li>
<p>Next, if the option or positional parameter has a <code>split</code> regex defined, the parameter value is split while respecting quotes: the <code>split</code> regex is not matched if it occurs in a quoted substring of the parameter value. Each of the parts found by the splitting process will have its quotes removed using the below "smart unquote" procedure.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>See the <a href="#_splitting_quoted_parameters">Splitting Quoted Parameters</a> section below for examples.</p>
</div>
<div class="sect4">
<h5 id="_smart_unquote">Smart Unquote</h5>
<div class="ulist">
<ul>
<li>
<p>If the command line argument contains just the leading and trailing quote, these quotes are removed.</p>
</li>
<li>
<p>If the command line argument contains unescaped quotes, other than the leading and trailing quote, the argument is unchanged (the leading and trailing quotes remain).</p>
</li>
<li>
<p>If a quoted command line argument contains backslash-escaped quotes, the leading and trailing quotes are removed, backslash-escaped quotes are converted to unescaped quotes, and backslash-escaped backslashes are converted to unescaped backslashes.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Command Line Argument</th>
<th class="tableblock halign-left valign-top">After Trimming Quotes</th>
<th class="tableblock halign-left valign-top">Note</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>"-x=abc"</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-x=abc</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">quotes removed</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>"a,b","x,y"</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>"a,b","x,y"</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">left unchanged</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>"-x=a,b,\"c,d,e\",f"</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-x=a,b,"c,d,e",f</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Splitting will find 4 values: <code>a</code>; <code>b</code>; <code>c,d,e</code>; and <code>f</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>"-x=\"a,b,\\"c,d,e\\",f\""</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>-x="a,b,\"c,d,e\",f"</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Splitting will find 1 value: <code>a,b,"c,d,e",f</code></p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect3">
<h4 id="_splitting_quoted_parameters">10.10.2. Splitting Quoted Parameters</h4>
<div class="paragraph">
<p>By default, if the option or positional parameter has a <a href="#_split_regex"><code>split</code></a> regex defined, parameter values are split into parts while respecting quotes: the <code>split</code> regular expression is not matched inside a quoted region.</p>
</div>
<div class="paragraph">
<p>Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>@Option(names = "-x", split = ",")
String[] parts;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Given input like below:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>&lt;command&gt; -x "-Dvalues=a,b,c","-Dother=1,2"</code></pre>
</div>
</div>
<div class="paragraph">
<p>This results in the <code>parts</code> array having the following values, assuming the parser configuration <code>trimQuotes</code> is <code>false</code> (the default):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>"-Dvalues=a,b,c"
"-Dother=1,2"</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the parser configuration <code>trimQuotes</code> is <code>true</code>, the above example would be split into the following values (with quotes trimmed from the resulting parts):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>-Dvalues=a,b,c
-Dother=1,2</code></pre>
</div>
</div>
<div class="paragraph">
<p>Given input like below:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>&lt;command&gt; -x a,b,"c,d,e",f,"xxx,yyy"</code></pre>
</div>
</div>
<div class="paragraph">
<p>This results in the <code>parts</code> array having the following values:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>a
b
"c,d,e"
f
"xxx,yyy"</code></pre>
</div>
</div>
<div class="paragraph">
<p>Or, if the parser configuration <code>trimQuotes</code> is <code>true</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>a
b
c,d,e
f
xxx,yyy</code></pre>
</div>
</div>
<div class="paragraph">
<p>To preserve quotes when <code>trimQuotes</code> is <code>true</code>, specify additional nested quotes on the command line. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>&lt;command&gt; "-x=\"a,b,\\"c,d,e\\",f\"" "x,y,z" "\"1,2,3\"" "\\"1,2,3\\""</code></pre>
</div>
</div>
<div class="paragraph">
<p>With parser configuration <code>trimQuotes</code> set to <code>true</code>, the above input gives the following values:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>a,b,"c,d,e",f
x
y
z
1,2,3
"1,2,3"</code></pre>
</div>
</div>
<div class="paragraph">
<p>This "smart splitting" (respecting quotes) can be switched off with <code>CommandLine::setSplitQuotedStrings</code>:
setting the <code>splitQuotedStrings</code> parser attribute to <code>true</code> switches off smart splitting,
and the <code>split</code> regex is applied to the parameter value regardless of quotes.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
<div class="paragraph">
<p><code>splitQuotedStrings</code> is mostly for backwards compatibility, for applications that want the pre-3.7 behaviour of simply splitting regardless of quotes.
Most applications should leave this setting to the default (<code>false</code>).
When this setting is <code>true</code>, the above input is parsed as:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>a
b
"c
d
e"
f
"xxx
yyy"</code></pre>
</div>
</div>
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_customizing_negatable_options">10.11. Customizing Negatable Options</h3>
<div class="paragraph">
<p><a href="#_negatable_options">Negatable options</a> can be customized via the <code>INegatableOptionTransformer</code> interface:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">interface</span> <span class="class">INegatableOptionTransformer</span> {
    <span class="comment">/**
     * Returns the negative form of the specified option name for the parser to recognize
     * when parsing command line arguments.
     * @param optionName the option name to create a negative form for,
     *                   for example {@code --force}
     * @param cmd the command that the option is part of
     * @return the negative form of the specified option name, for example {@code --no-force}
     */</span>
    <span class="predefined-type">String</span> makeNegative(<span class="predefined-type">String</span> optionName, CommandSpec cmd);

    <span class="comment">/**
     * Returns the documentation string to show in the synopsis and usage help message for
     * the specified option. The returned value should be concise and clearly suggest that
     * both the positive and the negative form are valid option names.
     * @param optionName the option name to create a documentation string for,
     *                   for example {@code --force}, or {@code -XX:+&lt;option&gt;}
     * @param cmd the command that the option is part of
     * @return the documentation string for the negatable option,
     *         for example {@code --[no-]force}, or {@code -XX:(+|-)&lt;option&gt;}
     */</span>
    <span class="predefined-type">String</span> makeSynopsis(<span class="predefined-type">String</span> optionName, CommandSpec cmd);
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This allows you to control:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>which option names should have a negative form</p>
</li>
<li>
<p>the negative form recognized by the parser while parsing the command line</p>
</li>
<li>
<p>the documentation string showing both the positive and the negative form in the usage help message</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>By default, a set of <a href="https://picocli.info/apidocs/picocli/CommandLine.RegexTransformer.html#createDefault--">regular expressions</a> is used to control the above.
Use <code>CommandLine.setNegatableOptionTransformer</code> to replace the <a href="https://picocli.info/apidocs/picocli/CommandLine.INegatableOptionTransformer"><code>INegatableOptionTransformer</code></a> with a custom version.
See the javadoc for details.</p>
</div>
</div>
<div class="sect2">
<h3 id="_custom_parameter_processing">10.12. Custom Parameter Processing</h3>
<div class="paragraph">
<p>Options or positional parameters can be assigned a <code>IParameterConsumer</code> that implements
custom logic to process the parameters for this option or this position.
When an option or positional parameter with a custom <code>IParameterConsumer</code>
is matched on the command line, picocli&#8217;s internal parser is temporarily suspended,
and the custom parameter consumer becomes responsible for consuming and processing as many
command line arguments as needed.</p>
</div>
<div class="paragraph">
<p>This can be useful when passing options through to another command.</p>
</div>
<div class="paragraph">
<p>For example, the unix <a href="https://en.wikipedia.org/wiki/Find_(Unix)"><code>find</code></a> command
has a <a href="https://en.wikipedia.org/wiki/Find_(Unix)#Execute_an_action"><code>-exec</code></a>
option to execute some action for each file found.
Any arguments following the <code>-exec</code> option until a <code>;</code> or <code>+</code> argument are not
options for the <code>find</code> command itself, but are interpreted as a separate command and its options.</p>
</div>
<div class="paragraph">
<p>The example below demonstrates how to implement <code>find -exec</code> using this API:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">find</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">Find</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-exec</span><span class="delimiter">&quot;</span></span>, parameterConsumer = ExecParameterConsumer.class)
    <span class="predefined-type">List</span>&lt;<span class="predefined-type">String</span>&gt; list = <span class="keyword">new</span> <span class="predefined-type">ArrayList</span>&lt;<span class="predefined-type">String</span>&gt;();
}

<span class="type">class</span> <span class="class">ExecParameterConsumer</span> <span class="directive">implements</span> IParameterConsumer {
    <span class="directive">public</span> <span class="type">void</span> consumeParameters(<span class="predefined-type">Stack</span>&lt;<span class="predefined-type">String</span>&gt; args, ArgSpec argSpec, CommandSpec commandSpec) {
        <span class="predefined-type">List</span>&lt;<span class="predefined-type">String</span>&gt; list = argSpec.getValue();
        <span class="keyword">while</span> (!args.isEmpty()) {
            <span class="predefined-type">String</span> arg = args.pop();
            list.add(arg);

            <span class="comment">// `find -exec` semantics: stop processing after a ';' or '+' argument</span>
            <span class="keyword">if</span> (<span class="string"><span class="delimiter">&quot;</span><span class="content">;</span><span class="delimiter">&quot;</span></span>.equals(arg) || <span class="string"><span class="delimiter">&quot;</span><span class="content">+</span><span class="delimiter">&quot;</span></span>.equals(arg)) {
                <span class="keyword">break</span>;
            }
        }
    }
}</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_help">11. Help</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_help_options">11.1. Help Options</h3>
<div class="paragraph">
<p>Applications can define help options by setting attribute <code>versionHelp = true</code>, <code>usageHelp = true</code> or <code>help = true</code>.
If one of the arguments specified on the command line is a "help" option, picocli will not throw a <code>MissingParameterException</code> when required options are missing.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-V</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--version</span><span class="delimiter">&quot;</span></span>}, versionHelp = <span class="predefined-constant">true</span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">display version info</span><span class="delimiter">&quot;</span></span>)
<span class="type">boolean</span> versionInfoRequested;

<span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-h</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--help</span><span class="delimiter">&quot;</span></span>}, usageHelp = <span class="predefined-constant">true</span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">display this help message</span><span class="delimiter">&quot;</span></span>)
<span class="type">boolean</span> usageHelpRequested;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Use these attributes for options that request the usage help message or version information to be shown on the console.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">App app = CommandLine.populateCommand(<span class="keyword">new</span> App(), args);
<span class="keyword">if</span> (app.usageHelpRequested) {
   CommandLine.usage(<span class="keyword">new</span> App(), <span class="predefined-type">System</span>.out);
   <span class="keyword">return</span>;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>CommandLine</code> class offers two methods that allow external components to detect whether
usage help or version information was requested (without inspecting the annotated domain object):</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>CommandLine.isUsageHelpRequested()</code> returns <code>true</code> if the parser matched an option annotated with <code>usageHelp=true</code></p>
</li>
<li>
<p><code>CommandLine.isVersionHelpRequested()</code> returns <code>true</code> if the parser matched an option annotated with <code>versionHelp=true</code></p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">CommandLine commandLine = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> App());
commandLine.parseArgs(args);
<span class="keyword">if</span> (commandLine.isUsageHelpRequested()) {
   commandLine.usage(<span class="predefined-type">System</span>.out);
   <span class="keyword">return</span>;
} <span class="keyword">else</span> <span class="keyword">if</span> (commandLine.isVersionHelpRequested()) {
   commandLine.printVersionHelp(<span class="predefined-type">System</span>.out);
   <span class="keyword">return</span>;
}
<span class="comment">// ... run App's business logic</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>See also <a href="#_printing_help_automatically">Printing Help Automatically</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_mixin_standard_help_options">11.2. Mixin Standard Help Options</h3>
<div class="paragraph">
<p>Picocli 3.0 introduced the <code>mixinStandardHelpOptions</code> command attribute. When this attribute is set to <code>true</code>, picocli adds a <a href="#_mixins">mixin</a> to the
command that adds <a href="#_help_options"><code>usageHelp</code></a> and <a href="#_help_options"><code>versionHelp</code></a> options to the command. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(mixinStandardHelpOptions = <span class="predefined-constant">true</span>, version = <span class="string"><span class="delimiter">&quot;</span><span class="content">auto help demo - picocli 3.0</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">AutoHelpDemo</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span> {

    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">--option</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Some option.</span><span class="delimiter">&quot;</span></span>)
    <span class="predefined-type">String</span> option;

    <span class="annotation">@Override</span> <span class="directive">public</span> <span class="type">void</span> run() { ... }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Commands with <code>mixinStandardHelpOptions</code> do not need to explicitly declare fields annotated with <code>@Option(usageHelp = true)</code> and <code>@Option(versionHelp = true)</code> any more.
The usage help message for the above example looks like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: &lt;main class&gt; [-hV] [--option=&lt;option&gt;]
      --option=&lt;option&gt;   Some option.
  -h, --help              Show this help message and exit.
  -V, --version           Print version information and exit.</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_built_in_help_subcommand">11.3. Built-in Help Subcommand</h3>
<div class="paragraph">
<p>From 3.0, picocli provides a <code>help</code> subcommand (<code>picocli.CommandLine.HelpCommand</code>) that can be installed as a subcommand
on any application command. It prints usage help for the parent command or sibling subcommands. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">picocli.CommandLine.HelpCommand</span>;

<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">myapp</span><span class="delimiter">&quot;</span></span>, subcommands = {HelpCommand.class, Subcommand.class})
<span class="type">class</span> <span class="class">MyCommand</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span> {
    <span class="comment">// ...</span>
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>For example, the following command prints usage help for a subcommand:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">myapp help subcommand</code></pre>
</div>
</div>
<div class="paragraph">
<p>To print usage help for the main command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">myapp help</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_custom_help_subcommands">11.4. Custom Help Subcommands</h3>
<div class="paragraph">
<p>Custom help subcommands should mark themselves as a <a href="#_help_subcommands">help command</a> to tell picocli not to throw a <code>MissingParameterException</code> when required options are missing.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(helpCommand = <span class="predefined-constant">true</span>)</code></pre>
</div>
</div>
<div class="paragraph">
<p>Picocli 4.0 introduced a new interface <code>picocli.CommandLine.IHelpCommandInitializable2</code> that provides custom help
commands with access to the parent command and sibling commands, whether to use Ansi colors or not, and the streams to print the usage help message to.</p>
</div>
<div class="paragraph">
<p>The <code>IHelpCommandInitializable2</code> interface replaces the <code>IHelpCommandInitializable</code> interface which was introduced in picocli 3.0.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">IHelpCommandInitializable2</span> {
    <span class="comment">/**
     * Initializes this object with the information needed to implement a help command that
     * provides usage help for other commands.
     *
     * @param helpCommandLine the {@code CommandLine} object associated with this help command.
      *                       Implementors can use this to walk the command hierarchy and
      *                       get access to the help command's parent and sibling commands.
     * @param colorScheme the color scheme to use when printing help, including whether
     *                    to use Ansi colors or not
     * @param outWriter the output writer to print the usage help message to
     * @param errWriter the error writer to print any diagnostic messages to,
     *                  in addition to the output from the exception handler
     */</span>
    <span class="type">void</span> init(CommandLine helpCommandLine,
              Help.ColorScheme colorScheme,
              <span class="predefined-type">PrintWriter</span> outWriter,
              <span class="predefined-type">PrintWriter</span> errWriter);
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_printing_help_automatically">11.5. Printing Help Automatically</h3>
<div class="paragraph">
<p>From picocli 2.0, the <a href="#execute">convenience methods</a> will automatically print usage help and version information
when a help option was specified on the command line (options annotated with the <code>versionHelp</code> or <code>usageHelp</code> attribute - but not the <code>help</code> attribute).</p>
</div>
<div class="paragraph">
<p>The same holds for the <code>mixinStandardHelpOptions</code> attribute, the built-in <code>HelpCommand</code> and any custom help subcommands marked as a <a href="#_help_subcommands">help command</a>.</p>
</div>
<div class="paragraph">
<p>The following <a href="#execute">convenience methods</a> automatically print help:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>CommandLine::execute</code></p>
</li>
<li>
<p><code>CommandLine::call</code></p>
</li>
<li>
<p><code>CommandLine::run</code></p>
</li>
<li>
<p><code>CommandLine::invoke</code></p>
</li>
<li>
<p><code>CommandLine::parseWithHandler</code> (with the built-in <code>Run&#8230;&#8203;</code> handlers)</p>
</li>
<li>
<p><code>CommandLine::parseWithHandlers</code> (with the built-in <code>Run&#8230;&#8203;</code> handlers)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The following methods <strong>do not</strong> automatically print help:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>CommandLine::parse</code></p>
</li>
<li>
<p><code>CommandLine::parseArgs</code></p>
</li>
<li>
<p><code>CommandLine::populateCommand</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>When using the last three methods, applications need to query the parse result to detect whether usage help or version help
was requested, and invoke <code>CommandLine::usage</code> or <code>CommandLine::printVersionHelp</code> to actually print the requested help message.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_version_help">12. Version Help</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_static_version_information">12.1. Static Version Information</h3>
<div class="sect3">
<h4 id="_command_version_attribute">12.1.1. Command <code>version</code> Attribute</h4>
<div class="paragraph">
<p>Since v0.9.8, applications can specify version information in the <code>version</code> attribute of the <code>@Command</code> annotation.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(version = <span class="string"><span class="delimiter">&quot;</span><span class="content">1.0</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">VersionedCommand</span> {
    <span class="annotation">@Option</span>(names = { <span class="string"><span class="delimiter">&quot;</span><span class="content">-V</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--version</span><span class="delimiter">&quot;</span></span> }, versionHelp = <span class="predefined-constant">true</span>,
            description = <span class="string"><span class="delimiter">&quot;</span><span class="content">print version information and exit</span><span class="delimiter">&quot;</span></span>)
    <span class="type">boolean</span> versionRequested;
    ...</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>CommandLine.printVersionHelp(PrintStream)</code> method extracts the version information from this
annotation and prints it to the specified <code>PrintStream</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">CommandLine commandLine = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> VersionedCommand());
commandLine.parseArgs(args);
<span class="keyword">if</span> (commandLine.isVersionHelpRequested()) {
    commandLine.printVersionHelp(<span class="predefined-type">System</span>.out);
    <span class="keyword">return</span>;
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_multi_line_version_info">12.1.2. Multi-line Version Info</h4>
<div class="paragraph">
<p>The <code>version</code> may specify multiple Strings. Each will be printed on a separate line.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(version = { <span class="string"><span class="delimiter">&quot;</span><span class="content">Versioned Command 1.0</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">Build 12345</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">(c) 2017</span><span class="delimiter">&quot;</span></span> })
<span class="type">class</span> <span class="class">VersionedCommand</span> { ... }</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>CommandLine.printVersionHelp(PrintStream)</code> method will print the above as:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Versioned Command 1.0
Build 12345
(c) 2017</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_version_info_with_variables">12.1.3. Version Info With Variables</h4>
<div class="paragraph">
<p>Since 4.0, the version strings may contain <a href="#_variable_interpolation">system properties and environment variables</a>. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(version = {
    <span class="string"><span class="delimiter">&quot;</span><span class="content">Versioned Command 1.0</span><span class="delimiter">&quot;</span></span>,
    <span class="string"><span class="delimiter">&quot;</span><span class="content">Picocli </span><span class="delimiter">&quot;</span></span> + picocli.CommandLine.VERSION,
    <span class="string"><span class="delimiter">&quot;</span><span class="content">JVM: ${java.version} (${java.vendor} ${java.vm.name} ${java.vm.version})</span><span class="delimiter">&quot;</span></span>,
    <span class="string"><span class="delimiter">&quot;</span><span class="content">OS: ${os.name} ${os.version} ${os.arch}</span><span class="delimiter">&quot;</span></span>})
<span class="type">class</span> <span class="class">VersionedCommand</span> { ... }</code></pre>
</div>
</div>
<div class="paragraph">
<p>Depending on your environment, that may print something like:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Versioned Command 1.0
Picocli 4.0.0
JVM: 1.8.0_202 (Oracle Corporation Substrate VM GraalVM 1.0.0-rc15 CE)
OS: Linux 4.4.0-17134-Microsoft amd64</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_version_info_with_colors">12.1.4. Version Info With Colors</h4>
<div class="paragraph">
<p>The version strings may contain <a href="#_usage_help_with_styles_and_colors">markup</a> to show ANSI styles and colors. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(version = {
        <span class="string"><span class="delimiter">&quot;</span><span class="content">@|yellow Versioned Command 1.0|@</span><span class="delimiter">&quot;</span></span>,
        <span class="string"><span class="delimiter">&quot;</span><span class="content">@|blue Build 12345|@</span><span class="delimiter">&quot;</span></span>,
        <span class="string"><span class="delimiter">&quot;</span><span class="content">@|red,bg(white) (c) 2017|@</span><span class="delimiter">&quot;</span></span> })
<span class="type">class</span> <span class="class">VersionedCommand</span> { ... }</code></pre>
</div>
</div>
<div class="paragraph">
<p>The markup will be rendered as ANSI escape codes on supported systems.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/VersionInfoWithColors.png" alt="Screenshot of version information containing markup with Ansi styles and colors"></span></p>
</div>
</div>
<div class="sect3">
<h4 id="_version_info_with_format_specifiers">12.1.5. Version Info With Format Specifiers</h4>
<div class="paragraph">
<p>From picocli 1.0, the <code>version</code> may contain <a href="#_format_specifiers">format specifiers</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(version = {
    <span class="string"><span class="delimiter">&quot;</span><span class="content">Versioned Command 1.0</span><span class="delimiter">&quot;</span></span>,
    <span class="string"><span class="delimiter">&quot;</span><span class="content">Build %1$s</span><span class="delimiter">&quot;</span></span>,
    <span class="string"><span class="delimiter">&quot;</span><span class="content">(c) 2017, licensed to %2$s</span><span class="delimiter">&quot;</span></span> })
<span class="type">class</span> <span class="class">VersionedCommand</span> { ... }</code></pre>
</div>
</div>
<div class="paragraph">
<p>Format argument values can be passed to the <code>printVersionHelp</code> method:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">String</span><span class="type">[]</span> args = {<span class="string"><span class="delimiter">&quot;</span><span class="content">1234</span><span class="delimiter">&quot;</span></span>, <span class="predefined-type">System</span>.getProperty(<span class="string"><span class="delimiter">&quot;</span><span class="content">user.name</span><span class="delimiter">&quot;</span></span>)};
<span class="keyword">new</span> CommandLine(<span class="keyword">new</span> VersionedCommand())
    .printVersionHelp(<span class="predefined-type">System</span>.out, Help.Ansi.AUTO, args);</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_dynamic_version_information">12.2. Dynamic Version Information</h3>
<div class="sect3">
<h4 id="_command_versionprovider_attribute">12.2.1. Command <code>versionProvider</code> Attribute</h4>
<div class="paragraph">
<p>From picocli 2.2, the <code>@Command</code> annotation supports a <code>versionProvider</code> attribute.
Applications may specify a <code>IVersionProvider</code> implementation in this attribute, and picocli will instantiate this class
and invoke it to collect version information.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(versionProvider = com.my.custom.ManifestVersionProvider.class)
<span class="type">class</span> <span class="class">App</span> { ... }</code></pre>
</div>
</div>
<div class="paragraph">
<p>This is useful when the version of an application should be detected dynamically at runtime.
For example, an implementation may return version information obtained from the JAR manifest, a properties file or some other source.</p>
</div>
</div>
<div class="sect3">
<h4 id="_iversionprovider_interface">12.2.2. <code>IVersionProvider</code> Interface</h4>
<div class="paragraph">
<p>Custom version providers need to implement the <code>picocli.CommandLine.IVersionProvider</code> interface:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">IVersionProvider</span> {
    <span class="comment">/**
     * Returns version information for a command.
     * @return version information (each string in the array is displayed on a separate line)
     * @throws Exception an exception detailing what went wrong when obtaining version information
     */</span>
    <span class="predefined-type">String</span><span class="type">[]</span> getVersion() <span class="directive">throws</span> <span class="exception">Exception</span>;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Version providers declared with the <code>versionProvider</code> attribute need to have a public no-argument constructor to be instantiated, unless a <a href="#_custom_factory">Custom Factory</a> is installed to instantiate classes.</p>
</div>
<div class="paragraph">
<p>The GitHub project has a manifest file-based
<a href="https://github.com/remkop/picocli/blob/master/picocli-examples/src/main/java/picocli/examples/VersionProviderDemo2.java">example</a>
and a build-generated version properties file-based
<a href="https://github.com/remkop/picocli/blob/master/picocli-examples/src/main/java/picocli/examples/VersionProviderDemo1.java">example</a> version provider implementation.</p>
</div>
</div>
<div class="sect3">
<h4 id="_dynamic_version_info_with_variables">12.2.3. Dynamic Version Info with Variables</h4>
<div class="paragraph">
<p>The version strings returned from the <code>IVersionProvider</code> may contain <a href="#_variable_interpolation">system properties and environment variables</a>.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">VersionProviderWithVariables</span> <span class="directive">implements</span> IVersionProvider {
    <span class="directive">public</span> <span class="predefined-type">String</span><span class="type">[]</span> getVersion() {
        <span class="keyword">return</span> <span class="keyword">new</span> <span class="predefined-type">String</span><span class="type">[]</span> { <span class="string"><span class="delimiter">&quot;</span><span class="content">${COMMAND-FULL-NAME} version 1.0</span><span class="delimiter">&quot;</span></span> };
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above example version provider will show the fully qualified command name (that is, preceded by its parent fully qualified command name)
of any command that uses this version provider.</p>
</div>
<div class="paragraph">
<p>This is one way to create a version provider that can be reused across multiple commands.</p>
</div>
</div>
<div class="sect3">
<h4 id="_injecting_commandspec_into_a_iversionprovider">12.2.4. Injecting <code>CommandSpec</code> Into a <code>IVersionProvider</code></h4>
<div class="paragraph">
<p>From picocli 4.2.0, <code>IVersionProvider</code> implementations can have <code>@Spec</code>-annotated fields. If such a field
exists, picocli will inject the <code>CommandSpec</code> of the command that uses this version provider.
This gives the version provider access to the full command hierarchy,
and may make it easier to implement version providers that can be reused among multiple commands.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">MyVersionProvider</span> <span class="directive">implements</span> IVersionProvider {
    <span class="annotation">@Spec</span> CommandSpec spec;

    <span class="directive">public</span> <span class="predefined-type">String</span><span class="type">[]</span> getVersion() {
        <span class="keyword">return</span> <span class="keyword">new</span> <span class="predefined-type">String</span><span class="type">[]</span> { <span class="string"><span class="delimiter">&quot;</span><span class="content">Version info for </span><span class="delimiter">&quot;</span></span> + spec.qualifiedName() };
    }
}</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_usage_help">13. Usage Help</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_compact_example">13.1. Compact Example</h3>
<div class="paragraph">
<p>A default picocli usage help message looks like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: cat [-AbeEnstTuv] [--help] [--version] [FILE...]
Concatenate FILE(s), or standard input, to standard output.
      FILE                 Files whose contents to display
  -A, --show-all           equivalent to -vET
  -b, --number-nonblank    number nonempty output lines, overrides -n
  -e                       equivalent to -vET
  -E, --show-ends          display $ at end of each line
  -n, --number             number all output lines
  -s, --squeeze-blank      suppress repeated empty output lines
  -t                       equivalent to -vT
  -T, --show-tabs          display TAB characters as ^I
  -u                       (ignored)
  -v, --show-nonprinting   use ^ and M- notation, except for LDF and TAB
      --help               display this help and exit
      --version            output version information and exit
Copyright(c) 2017</pre>
</div>
</div>
<div class="paragraph">
<p>The usage help message is generated from annotation attributes, like below:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">cat</span><span class="delimiter">&quot;</span></span>, footer = <span class="string"><span class="delimiter">&quot;</span><span class="content">Copyright(c) 2017</span><span class="delimiter">&quot;</span></span>,
         description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Concatenate FILE(s), or standard input, to standard output.</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">Cat</span> {

  <span class="annotation">@Parameters</span>(paramLabel = <span class="string"><span class="delimiter">&quot;</span><span class="content">FILE</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Files whose contents to display</span><span class="delimiter">&quot;</span></span>)
  <span class="predefined-type">List</span>&lt;<span class="predefined-type">File</span>&gt; files;

  <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">--help</span><span class="delimiter">&quot;</span></span>, usageHelp = <span class="predefined-constant">true</span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">display this help and exit</span><span class="delimiter">&quot;</span></span>)
  <span class="type">boolean</span> help;

  <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-t</span><span class="delimiter">&quot;</span></span>,                 description = <span class="string"><span class="delimiter">&quot;</span><span class="content">equivalent to -vT</span><span class="delimiter">&quot;</span></span>)  <span class="type">boolean</span> t;
  <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-e</span><span class="delimiter">&quot;</span></span>,                 description = <span class="string"><span class="delimiter">&quot;</span><span class="content">equivalent to -vET</span><span class="delimiter">&quot;</span></span>) <span class="type">boolean</span> e;
  <span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-A</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--show-all</span><span class="delimiter">&quot;</span></span>}, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">equivalent to -vET</span><span class="delimiter">&quot;</span></span>) <span class="type">boolean</span> all;

  <span class="comment">// ...</span>
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_command_name">13.2. Command Name</h3>
<div class="paragraph">
<p>In the above example, the program name is taken from the <code>name</code> attribute of the <code>Command</code> annotation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">cat</span><span class="delimiter">&quot;</span></span>)</code></pre>
</div>
</div>
<div class="paragraph">
<p>Without a <code>name</code> attribute, picocli will show a generic <code>&lt;main class&gt;</code> in the synopsis:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: &lt;main class&gt; [-AbeEnstTuv] [--help] [--version] [FILE...]</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_parameter_labels">13.3. Parameter Labels</h3>
<div class="paragraph">
<p>Non-boolean options require a value. The usage help should explain this, and picocli shows the option parameter
in the synopsis and in the option list. By default, the field name is shown in <code>&lt;</code> and <code>&gt;</code> fish brackets.
Use the <code>paramLabel</code> attribute to display a different name. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: &lt;main class&gt; [-f=FILE] [-n=&lt;number&gt;] NUM &lt;host&gt;
      NUM        number param
      host       the host parameter
  -f= FILE       a file
  -n= &lt;number&gt;   a number option</pre>
</div>
</div>
<div class="paragraph">
<p>Some annotated fields in the below example class have a <code>paramLabel</code> attribute and others don&#8217;t:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>()
<span class="type">class</span> <span class="class">ParamLabels</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-f</span><span class="delimiter">&quot;</span></span>,    description = <span class="string"><span class="delimiter">&quot;</span><span class="content">a file</span><span class="delimiter">&quot;</span></span>,       paramLabel = <span class="string"><span class="delimiter">&quot;</span><span class="content">FILE</span><span class="delimiter">&quot;</span></span>) <span class="predefined-type">File</span> f;
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-n</span><span class="delimiter">&quot;</span></span>,    description = <span class="string"><span class="delimiter">&quot;</span><span class="content">a number option</span><span class="delimiter">&quot;</span></span>)                   <span class="type">int</span> number;
    <span class="annotation">@Parameters</span>(index = <span class="string"><span class="delimiter">&quot;</span><span class="content">0</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">number param</span><span class="delimiter">&quot;</span></span>, paramLabel = <span class="string"><span class="delimiter">&quot;</span><span class="content">NUM</span><span class="delimiter">&quot;</span></span>)  <span class="type">int</span> n;
    <span class="annotation">@Parameters</span>(index = <span class="string"><span class="delimiter">&quot;</span><span class="content">1</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">the host parameter</span><span class="delimiter">&quot;</span></span>)                <span class="predefined-type">InetAddress</span> host;
}</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
For demonstration purposes the above example mixes the all-uppercase (e.g., <code>NUM</code>) style label and the fish bracket (e.g., <code>&lt;number&gt;</code>) style labels. For real applications, mixing these label styles should be avoided. An application should consistently use only one style.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_unsorted_option_list">13.4. Unsorted Option List</h3>
<div class="paragraph">
<p>By default the options list displays options in alphabetical order. Use the <code>sortOptions = false</code> attribute to display options in the order they are declared in your class.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(sortOptions = <span class="predefined-constant">false</span>)</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_reordering_options">13.5. Reordering Options</h3>
<div class="paragraph">
<p>When mixing <code>@Option</code> methods and <code>@Option</code> fields, options do not reliably appear in declaration order.</p>
</div>
<div class="paragraph">
<p>The <code>@Option(order = &lt;int&gt;)</code> attribute can be used to explicitly control the position in the usage help message at which the option should be shown.
Options with a lower number are shown before options with a higher number.</p>
</div>
</div>
<div class="sect2">
<h3 id="_abbreviated_synopsis">13.6. Abbreviated Synopsis</h3>
<div class="paragraph">
<p>If a command is very complex and has many options, it is sometimes desirable to suppress details from the synopsis with the <code>abbreviateSynopsis</code> attribute. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: &lt;main class&gt; [OPTIONS] [&lt;files&gt;...]</pre>
</div>
</div>
<div class="paragraph">
<p>Note that the positional parameters are not abbreviated.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(abbreviateSynopsis = <span class="predefined-constant">true</span>)
<span class="type">class</span> <span class="class">App</span> {
    <span class="annotation">@Parameters</span> <span class="predefined-type">File</span><span class="type">[]</span> files;
    <span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">--count</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">-c</span><span class="delimiter">&quot;</span></span>}) <span class="type">int</span> count;
    ....
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_custom_synopsis">13.7. Custom Synopsis</h3>
<div class="paragraph">
<p>For even more control of the synopsis, use the <code>customSynopsis</code> attribute to specify one ore more synopsis lines. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: ln [OPTION]... [-T] TARGET LINK_NAME   (1st form)
  or:  ln [OPTION]... TARGET                  (2nd form)
  or:  ln [OPTION]... TARGET... DIRECTORY     (3rd form)
  or:  ln [OPTION]... -t DIRECTORY TARGET...  (4th form)</pre>
</div>
</div>
<div class="paragraph">
<p>To produce a synopsis like the above, specify the literal text in the <code>customSynopsis</code> attribute:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(synopsisHeading = <span class="string"><span class="delimiter">&quot;</span><span class="delimiter">&quot;</span></span>, customSynopsis = {
        <span class="string"><span class="delimiter">&quot;</span><span class="content">Usage: ln [OPTION]... [-T] TARGET LINK_NAME   (1st form)</span><span class="delimiter">&quot;</span></span>,
        <span class="string"><span class="delimiter">&quot;</span><span class="content">  or:  ln [OPTION]... TARGET                  (2nd form)</span><span class="delimiter">&quot;</span></span>,
        <span class="string"><span class="delimiter">&quot;</span><span class="content">  or:  ln [OPTION]... TARGET... DIRECTORY     (3rd form)</span><span class="delimiter">&quot;</span></span>,
        <span class="string"><span class="delimiter">&quot;</span><span class="content">  or:  ln [OPTION]... -t DIRECTORY TARGET...  (4th form)</span><span class="delimiter">&quot;</span></span>,
})
<span class="type">class</span> <span class="class">Ln</span> { ... }</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_synopsis_subcommand_label">13.8. Synopsis Subcommand Label</h3>
<div class="paragraph">
<p>For commands with <a href="#_usage_help_for_subcommands">subcommands</a>, the string <code>[COMMAND]</code> is appended to the end of the synopsis (whether the synopsis is <a href="#_abbreviated_synopsis">abbreviated</a> or not). This looks something like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: &lt;cmd&gt; [OPTIONS] FILES [COMMAND]</pre>
</div>
</div>
<div class="paragraph">
<p>From picocli 4.0, this can be customized with the <code>synopsisSubcommandLabel</code> attribute.</p>
</div>
<div class="paragraph">
<p>For example, to clarify that a <a href="#_required_subcommands">subcommand is mandatory</a>, an application may specify <code>COMMAND</code>, without the <code>[</code> and <code>]</code> brackets:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">git</span><span class="delimiter">&quot;</span></span>, synopsisSubcommandLabel = <span class="string"><span class="delimiter">&quot;</span><span class="content">COMMAND</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">Git</span> { ... }</code></pre>
</div>
</div>
<div class="paragraph">
<p>An application with a limited number of subcommands may want to show them all in the synopsis, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">fs</span><span class="delimiter">&quot;</span></span>, synopsisSubcommandLabel = <span class="string"><span class="delimiter">&quot;</span><span class="content">(list | add | delete)</span><span class="delimiter">&quot;</span></span>,
         subcommands = {<span class="predefined-type">List</span>.class, Add.class, Delete.class}, mixinStandardHelpOptions = <span class="predefined-constant">true</span>)
<span class="type">class</span> <span class="class">Fs</span> { ... }</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will show the following synopsis:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: fs [-hV] (list | add | delete)</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_header_and_footer">13.9. Header and Footer</h3>
<div class="paragraph">
<p>The <code>header</code> will be shown at the top of the usage help message (before the synopsis). The first header line is also the line shown in the subcommand list if your command has subcommands (see <a href="#_usage_help_for_subcommands">Usage Help for Subcommands</a>).</p>
</div>
<div class="paragraph">
<p>Use the <code>footer</code> attribute to specify one or more lines to show below the generated usage help message.</p>
</div>
<div class="paragraph">
<p>Each element of the attribute String array is displayed on a separate line.</p>
</div>
</div>
<div class="sect2">
<h3 id="_exit_code_list">13.10. Exit Code List</h3>
<div class="paragraph">
<p>By default, the usage help message does not display <a href="#_generating_an_exit_code">exit code</a> information.
Applications that call <code>System.exit</code> need to configure the <code>exitCodeListHeading</code> and <code>exitCodeList</code> annotation attributes.
For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(mixinStandardHelpOptions = <span class="predefined-constant">true</span>,
        exitCodeListHeading = <span class="string"><span class="delimiter">&quot;</span><span class="content">Exit Codes:%n</span><span class="delimiter">&quot;</span></span>,
        exitCodeList = {
            <span class="string"><span class="delimiter">&quot;</span><span class="content"> 0:Successful program execution</span><span class="delimiter">&quot;</span></span>,
            <span class="string"><span class="delimiter">&quot;</span><span class="content">64:Usage error: user input for the command was incorrect, </span><span class="delimiter">&quot;</span></span> +
                    <span class="string"><span class="delimiter">&quot;</span><span class="content">e.g., the wrong number of arguments, a bad flag, </span><span class="delimiter">&quot;</span></span> +
                    <span class="string"><span class="delimiter">&quot;</span><span class="content">a bad syntax in a parameter, etc.</span><span class="delimiter">&quot;</span></span>,
            <span class="string"><span class="delimiter">&quot;</span><span class="content">70:Internal software error: an exception occurred when invoking </span><span class="delimiter">&quot;</span></span> +
                    <span class="string"><span class="delimiter">&quot;</span><span class="content">the business logic of this command.</span><span class="delimiter">&quot;</span></span>})
<span class="type">class</span> <span class="class">App</span> {}
<span class="keyword">new</span> CommandLine(<span class="keyword">new</span> App()).usage(<span class="predefined-type">System</span>.out);</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will print the following usage help message to the console:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>Usage: &lt;main class&gt;
Exit Codes:
   0   Successful program execution
  64   Usage error: user input for the command was incorrect, e.g., the wrong
         number of arguments, a bad flag, a bad syntax in a parameter, etc.
  70   Internal software error: an exception occurred when invoking the
         business logic of this command.</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_format_specifiers">13.11. Format Specifiers</h3>
<div class="paragraph">
<p>All usage help message elements can have embedded line separator (<code>%n</code>) format specifiers.
These are converted to the platform-specific line separator when the usage help message is printed.</p>
</div>
<div class="paragraph">
<p><a href="#_static_version_information">Version help</a> may have format specifiers that format additional arguments passed to the <code>printVersionHelp</code> method.</p>
</div>
<div class="paragraph">
<p>See the <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Formatter.html">java.util.Formatter javadoc</a> for details.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
Note that to show percent <code>'%'</code> characters in the usage help message, they need to be escaped with another <code>%</code>. For example: <code>@Parameters(description = "%%-age of the total")</code> is rendered as <code>%-age of the total</code>.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>An alternative way to control the layout of the usage help message is that some sections (<code>header</code>, <code>footer</code>, and <code>description</code>) can be specified as an array of Strings,
where each element of the array is displayed on a separate line in the usage help message.</p>
</div>
</div>
<div class="sect2">
<h3 id="_section_headings">13.12. Section Headings</h3>
<div class="paragraph">
<p>Section headers can be used to make usage message layout appear more spacious. The example below demonstrates the use of embedded line separator (<code>%n</code>) format specifiers:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">commit</span><span class="delimiter">&quot;</span></span>,
        sortOptions = <span class="predefined-constant">false</span>,
        headerHeading = <span class="string"><span class="delimiter">&quot;</span><span class="content">Usage:%n%n</span><span class="delimiter">&quot;</span></span>,
        synopsisHeading = <span class="string"><span class="delimiter">&quot;</span><span class="content">%n</span><span class="delimiter">&quot;</span></span>,
        descriptionHeading = <span class="string"><span class="delimiter">&quot;</span><span class="content">%nDescription:%n%n</span><span class="delimiter">&quot;</span></span>,
        parameterListHeading = <span class="string"><span class="delimiter">&quot;</span><span class="content">%nParameters:%n</span><span class="delimiter">&quot;</span></span>,
        optionListHeading = <span class="string"><span class="delimiter">&quot;</span><span class="content">%nOptions:%n</span><span class="delimiter">&quot;</span></span>,
        header = <span class="string"><span class="delimiter">&quot;</span><span class="content">Record changes to the repository.</span><span class="delimiter">&quot;</span></span>,
        description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Stores the current contents of the index in a new commit </span><span class="delimiter">&quot;</span></span> +
                <span class="string"><span class="delimiter">&quot;</span><span class="content">along with a log message from the user describing the changes.</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">GitCommit</span> { ... }</code></pre>
</div>
</div>
<div class="paragraph">
<p>The usage help message generated from this class is shown below in <a href="#_expanded_example">Expanded Example</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_expanded_example">13.13. Expanded Example</h3>
<div class="paragraph">
<p>The below example demonstrates what a customized usage message can look like.
Note how section headings with line separators can create a more spacious usage message,
and also that options are listed in declaration order (instead of in alphabetic order).</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage:

Record changes to the repository.

git commit [-ap] [--fixup=&lt;commit&gt;] [--squash=&lt;commit&gt;] [-c=&lt;commit&gt;]
           [-C=&lt;commit&gt;] [-F=&lt;file&gt;] [-m[=&lt;msg&gt;...]] [&lt;files&gt;...]

Description:

Stores the current contents of the index in a new commit along with a log
message from the user describing the changes.

Parameters:
      &lt;files&gt;                 the files to commit

Options:
  -a, --all                   Tell the command to automatically stage files
                                that have been modified and deleted, but new
                                files you have not told Git about are not
                                affected.
  -p, --patch                 Use the interactive patch selection interface to
                                chose which changes to commit
  -C, --reuse-message=&lt;commit&gt;
                              Take an existing commit object, and reuse the log
                                message and the authorship information
                                (including the timestamp) when creating the
                                commit.
  -c, --reedit-message=&lt;commit&gt;
                              Like -C, but with -c the editor is invoked, so
                                that the user can further edit the commit
                                message.
      --fixup=&lt;commit&gt;        Construct a commit message for use with rebase
                                --autosquash.
      --squash=&lt;commit&gt;        Construct a commit message for use with rebase
                                --autosquash. The commit message subject line is
                                taken from the specified commit with a prefix
                                of "squash! ". Can be used with additional
                                commit message options (-m/-c/-C/-F).
  -F, --file=&lt;file&gt;           Take the commit message from the given file. Use
                                - to read the message from the standard input.
  -m, --message[=&lt;msg&gt;...]     Use the given &lt;msg&gt; as the commit message. If
                                multiple -m options are given, their values are
                                concatenated as separate paragraphs.</pre>
</div>
</div>
<div class="paragraph">
<p>The annotated class that this usage help message is generated from is shown in <a href="#_section_headings">Section Headings</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_option_parameter_separators">13.14. Option-Parameter Separators</h3>
<div class="paragraph">
<p>The separator displayed between options and option parameters (<code>=</code> by default)
in the synopsis and the option list can be configured with the <code>separator</code> attribute.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(separator = <span class="string"><span class="delimiter">&quot;</span><span class="content"> </span><span class="delimiter">&quot;</span></span>)</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
the <code>@Command(separator = " ")</code> annotation also affects how picocli parses the command line.  See also <a href="#_custom_separators">Custom Separators</a>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_hidden_options_and_parameters">13.15. Hidden Options and Parameters</h3>
<div class="paragraph">
<p>Options and Parameters with the <code>hidden</code> attribute set to <code>true</code> will not be shown in the usage help message.
This is useful for example when a parameter at some index is captured into multiple fields:
by default each of these fields would be shown in the usage message, which would be confusing for users.</p>
</div>
<div class="paragraph">
<p>For example, the <code>all</code> field below is annotated as <code>hidden = true</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>()
<span class="type">class</span> <span class="class">App</span> {
    <span class="annotation">@Parameters</span>(index = <span class="string"><span class="delimiter">&quot;</span><span class="content">0</span><span class="delimiter">&quot;</span></span>,    description = <span class="string"><span class="delimiter">&quot;</span><span class="content">destination host</span><span class="delimiter">&quot;</span></span>)  <span class="predefined-type">InetAddress</span> host;
    <span class="annotation">@Parameters</span>(index = <span class="string"><span class="delimiter">&quot;</span><span class="content">1</span><span class="delimiter">&quot;</span></span>,    description = <span class="string"><span class="delimiter">&quot;</span><span class="content">destination port</span><span class="delimiter">&quot;</span></span>)  <span class="type">int</span> port;
    <span class="annotation">@Parameters</span>(index = <span class="string"><span class="delimiter">&quot;</span><span class="content">2..*</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">files to transfer</span><span class="delimiter">&quot;</span></span>) <span class="predefined-type">String</span><span class="type">[]</span> files;

    <span class="annotation">@Parameters</span>(hidden = <span class="predefined-constant">true</span>) <span class="predefined-type">String</span><span class="type">[]</span> all;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above will generate the following usage help message, where the <code>all</code> field is not shown:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: &lt;main class&gt; &lt;host&gt; &lt;port&gt; [&lt;files&gt;...]
      host    destination host
      port    destination port
      files   files to transfer</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_show_at_files">13.16. Show At Files</h3>
<div class="paragraph">
<p>From picocli 4.2, an entry for <code>@&lt;filename&gt;</code> can be shown in the options and parameters list of the usage help message of a command with the <code>@Command(showAtFileInUsageHelp = true)</code> annotation.</p>
</div>
<div class="sect3">
<h4 id="_example_2">13.16.1. Example</h4>
<div class="paragraph">
<p>Example command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">myapp</span><span class="delimiter">&quot;</span></span>, showAtFileInUsageHelp = <span class="predefined-constant">true</span>,
        mixinStandardHelpOptions = <span class="predefined-constant">true</span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Example command.</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">MyApp</span> {
    <span class="annotation">@Parameters</span>(description = <span class="string"><span class="delimiter">&quot;</span><span class="content">A file.</span><span class="delimiter">&quot;</span></span>) <span class="predefined-type">File</span> file;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The usage help message for this command looks like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: myapp [-hV] [@&lt;filename&gt;...] &lt;file&gt;
Example command.
      [@&lt;filename&gt;...]   One or more argument files containing options.
      &lt;file&gt;             A file.
  -h, --help             Show this help message and exit.
  -V, --version          Print version information and exit.</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_changing_the_at_file_entry_location">13.16.2. Changing the At File Entry Location</h4>
<div class="paragraph">
<p>By default, the <code>@&lt;filename&gt;</code> entry is shown before the positional parameters in the synopsis as well as in the parameters list.</p>
</div>
<div class="paragraph">
<p>This can be changed with the <a href="#_usage_help_api">Help API</a> for reordering sections. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">static</span> <span class="include">picocli.CommandLine.Model.UsageMessageSpec.SECTION_KEY_AT_FILE_PARAMETER</span>;
<span class="keyword">import</span> <span class="include">static</span> <span class="include">picocli.CommandLine.Model.UsageMessageSpec.SECTION_KEY_COMMAND_LIST_HEADING</span>;
<span class="keyword">import</span> <span class="include">static</span> <span class="include">picocli.CommandLine.Model.UsageMessageSpec.SECTION_KEY_OPTION_LIST_HEADING</span>;

<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">myapp</span><span class="delimiter">&quot;</span></span>, showAtFileInUsageHelp = <span class="predefined-constant">true</span>,
        mixinStandardHelpOptions = <span class="predefined-constant">true</span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Example command.</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">MyApp</span> {
    <span class="annotation">@Parameters</span>(description = <span class="string"><span class="delimiter">&quot;</span><span class="content">A file.</span><span class="delimiter">&quot;</span></span>) <span class="predefined-type">File</span> file;

    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span>... args) {
        CommandLine cmd = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MyApp());
        <span class="predefined-type">List</span>&lt;<span class="predefined-type">String</span>&gt; copy = <span class="keyword">new</span> <span class="predefined-type">ArrayList</span>&lt;&gt;(cmd.getHelpSectionKeys());
        copy.remove(SECTION_KEY_AT_FILE_PARAMETER);
        copy.add(copy.indexOf(SECTION_KEY_COMMAND_LIST_HEADING), SECTION_KEY_AT_FILE_PARAMETER);
        cmd.setHelpSectionKeys(copy);

        cmd.usage(<span class="predefined-type">System</span>.out);
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The resulting usage help message shows the <code>@&lt;filename&gt;</code> entry has moved to the bottom, following the options list:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: myapp [-hV] [@&lt;filename&gt;...] &lt;file&gt;
Example command.
      &lt;file&gt;             A file.
  -h, --help             Show this help message and exit.
  -V, --version          Print version information and exit.
      [@&lt;filename&gt;...]   One or more argument files containing options.</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_changing_the_at_file_entry_text">13.16.3. Changing the At File Entry Text</h4>
<div class="paragraph">
<p>Both the label and the description of the <code>@&lt;filename&gt;</code> entry have been defined with <a href="#_custom_variables">custom variables</a>, to allow applications to change the text. The variables are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>picocli.atfile.label</code></p>
</li>
<li>
<p><code>picocli.atfile.description</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>By setting the above variables in either system properties, environment variables or the <a href="#_internationalization">resource bundle</a> for a command, the text can be customized.</p>
</div>
<div class="paragraph">
<p>For example, if we define these system properties:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">System</span>.setProperty(<span class="string"><span class="delimiter">&quot;</span><span class="content">picocli.atfile.label</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">my@@@@file</span><span class="delimiter">&quot;</span></span>);
<span class="predefined-type">System</span>.setProperty(<span class="string"><span class="delimiter">&quot;</span><span class="content">picocli.atfile.description</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">@files rock!</span><span class="delimiter">&quot;</span></span>);</code></pre>
</div>
</div>
<div class="paragraph">
<p>then the usage help for our above example changes to this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: myapp [-hV] [my@@@@file...] &lt;file&gt;
Example command.
      [my@@@@file...]   @files rock!
      &lt;file&gt;            A file.
  -h, --help            Show this help message and exit.
  -V, --version         Print version information and exit.</pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_show_default_values">13.17. Show Default Values</h3>
<div class="sect3">
<h4 id="_default_value_variable">13.17.1. <code>${DEFAULT-VALUE}</code> Variable</h4>
<div class="paragraph">
<p>From picocli 3.2, it is possible to embed the <a href="#_default_values">default values</a> in the description for an option or positional parameter by
specifying the <a href="#_variable_interpolation">variable</a> <code>${DEFAULT-VALUE}</code> in the description text.
Picocli uses reflection to get the default values from the annotated fields.</p>
</div>
<div class="paragraph">
<p>The <a href="#_variable_interpolation">variable</a> is replaced with the default value regardless of the <code>@Command(showDefaultValues)</code> attribute
and regardless of the <code>@Option(showDefaultValues)</code> or <code>@Parameters(showDefaultValues)</code> attribute.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">DefaultValues</span> {
    <span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-f</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--file</span><span class="delimiter">&quot;</span></span>}, defaultValue = <span class="string"><span class="delimiter">&quot;</span><span class="content">config.xml</span><span class="delimiter">&quot;</span></span>,
            description = <span class="string"><span class="delimiter">&quot;</span><span class="content">the file to use (default: ${DEFAULT-VALUE})</span><span class="delimiter">&quot;</span></span>)
    <span class="predefined-type">File</span> file;
}

CommandLine.usage(<span class="keyword">new</span> DefaultValues(), <span class="predefined-type">System</span>.out);</code></pre>
</div>
</div>
<div class="paragraph">
<p>This produces the following usage help:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: &lt;main class&gt; -f=&lt;file&gt;
  -f, --file=&lt;file&gt;   the file to use (default: config.xml)</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_completion_candidates_variable">13.17.2. <code>${COMPLETION-CANDIDATES}</code> Variable</h4>
<div class="paragraph">
<p>Similarly, it is possible to embed the completion candidates in the description for an option or positional parameter by
specifying the <a href="#_variable_interpolation">variable</a> <code>${COMPLETION-CANDIDATES}</code> in the description text.</p>
</div>
<div class="paragraph">
<p>This works for java <code>enum</code> classes and for options or positional parameters of non-enum types for which completion candidates are specified.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">enum</span> Lang { java, groovy, kotlin, javascript, frege, clojure }

<span class="directive">static</span> <span class="type">class</span> <span class="class">MyAbcCandidates</span> <span class="directive">extends</span> <span class="predefined-type">ArrayList</span>&lt;<span class="predefined-type">String</span>&gt; {
    MyAbcCandidates() { <span class="local-variable">super</span>(<span class="predefined-type">Arrays</span>.asList(<span class="string"><span class="delimiter">&quot;</span><span class="content">A</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">B</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">C</span><span class="delimiter">&quot;</span></span>)); }
}

<span class="type">class</span> <span class="class">ValidValuesDemo</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-l</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Enum values: ${COMPLETION-CANDIDATES}</span><span class="delimiter">&quot;</span></span>)
    Lang lang = <span class="predefined-constant">null</span>;

    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-o</span><span class="delimiter">&quot;</span></span>, completionCandidates = MyAbcCandidates.class,
            description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Candidates: ${COMPLETION-CANDIDATES}</span><span class="delimiter">&quot;</span></span>)
    <span class="predefined-type">String</span> option;
}

CommandLine.usage(<span class="keyword">new</span> ValidValuesDemo(), <span class="predefined-type">System</span>.out);</code></pre>
</div>
</div>
<div class="paragraph">
<p>This produces the following usage help:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: &lt;main class&gt; [-l=&lt;lang&gt;] [-o=&lt;option&gt;]
  -l=&lt;lang&gt;     Enum values: java, groovy, kotlin, javascript, frege, clojure
  -o=&lt;option&gt;   Candidates: A, B, C</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_legacy_configuration_for_displaying_default_values">13.17.3. Legacy Configuration for Displaying Default Values</h4>
<div class="paragraph">
<p>Prior to picocli 3.2, you need to use the <code>@Command(showDefaultValues = true)</code> attribute to append the default value of
 all non-<code>null</code> options and positional parameters to the description column.</p>
</div>
<div class="paragraph">
<p>Additionally, picocli 3.0 introduced a <code>showDefaultValue</code> attribute to the <code>@Option</code> and <code>@Parameters</code> annotation.
This allows you to specify for each individual option and positional parameter whether its default value should be shown in the usage help.
This attribute accepts three values:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>ALWAYS</code> - always display the default value of this option or positional parameter, even <code>null</code> values, regardless what value of <code>showDefaultValues</code> was specified on the command</p>
</li>
<li>
<p><code>NEVER</code> - don&#8217;t show the default value for this option or positional parameter, regardless what value of <code>showDefaultValues</code> was specified on the command</p>
</li>
<li>
<p><code>ON_DEMAND</code> - (this is the default) only show the default value for this option or positional parameter if <code>showDefaultValues</code> was specified on the command</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>These legacy mechanisms still work but for maximum flexibility use the variables explained above.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_required_option_marker">13.18. Required-Option Marker</h3>
<div class="paragraph">
<p>Required options can be marked in the option list by the character specified with the <code>requiredOptionMarker</code> attribute. By default options are not marked because the synopsis shows users which options are required and which are optional. This feature may be useful in combination with the <a href="#_abbreviated_synopsis"><code>abbreviateSynopsis</code></a> attribute. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(requiredOptionMarker = <span class="string"><span class="delimiter">'</span><span class="content">*</span><span class="delimiter">'</span></span>, abbreviateSynopsis = <span class="predefined-constant">true</span>)
<span class="type">class</span> <span class="class">Example</span> {
    <span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-a</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--alpha</span><span class="delimiter">&quot;</span></span>}, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">optional alpha</span><span class="delimiter">&quot;</span></span>) <span class="predefined-type">String</span> alpha;
    <span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-b</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--beta</span><span class="delimiter">&quot;</span></span>}, required = <span class="predefined-constant">true</span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">mandatory beta</span><span class="delimiter">&quot;</span></span>) <span class="predefined-type">String</span> beta;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Produces the following usage help message:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: &lt;main class&gt; [OPTIONS]
  -a, --alpha=&lt;alpha&gt;   optional alpha
* -b, --beta=&lt;beta&gt;     mandatory beta</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_usage_width">13.19. Usage Width</h3>
<div class="paragraph">
<p>The default width of the usage help message is 80 characters.
Commands defined with <code>@Command(usageHelpWidth = NUMBER)</code> in the annotations will use the specified width.</p>
</div>
<div class="paragraph">
<p>Picocli 3.0 also introduced programmatic API for this via the <code>CommandLine::setUsageHelpWidth</code> and <code>UsageMessageSpec::width</code> methods.</p>
</div>
<div class="paragraph">
<p>End users can use system property <code>picocli.usage.width</code> to specify a custom width that overrides the programmatically set value.</p>
</div>
<div class="paragraph">
<p>The minimum width that can be configured is 55 characters.</p>
</div>
</div>
<div class="sect2">
<h3 id="_auto_terminal_width">13.20. Auto (Terminal) Width</h3>
<div class="paragraph">
<p>From 4.0, commands defined with <code>@Command(usageHelpAutoWidth = true)</code> will try to adjust the usage message help layout to the terminal width.
There is also programmatic API to control this via the <code>CommandLine::setUsageHelpAutoWidth</code> and <code>UsageMessageSpec::autoWidth</code> methods.</p>
</div>
<div class="paragraph">
<p>End users may enable this by setting system property <code>picocli.usage.width</code> to <code>AUTO</code>, and may disable this by setting this system property to a numeric value.</p>
</div>
<div class="paragraph">
<p>This feature requires Java 7.</p>
</div>
</div>
<div class="sect2">
<h3 id="_long_option_column_width">13.21. Long Option Column Width</h3>
<div class="paragraph">
<p>The default layout shows short options and long options in separate columns, followed by the description column.
The width of the long options column shrinks automatically if all long options are very short,
but by default this column does not grow larger than 20 characters.</p>
</div>
<div class="paragraph">
<p>If the long option with its option parameter is longer than 20 characters
(for example: <code>--output=&lt;outputFolder&gt;</code>), the long option overflows into the description column, and the option description is shown on the next line.</p>
</div>
<div class="paragraph">
<p>This (the default) looks like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: myapp [-hV] [-o=&lt;outputFolder&gt;]
  -h, --help      Show this help message and exit.
  -o, --output=&lt;outputFolder&gt;
                  Output location full path.
  -V, --version   Print version information and exit.</pre>
</div>
</div>
<div class="paragraph">
<p>From picocli 4.2, there is programmatic API to change this via the <code>CommandLine::setLongOptionsMaxWidth</code> and <code>UsageMessageSpec::longOptionsMaxWidth</code> methods.</p>
</div>
<div class="paragraph">
<p>In the above example, if we call <code>commandLine.setLongOptionsMaxWidth(23)</code> before printing the usage help, we get this result:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: myapp [-hV] [-o=&lt;outputFolder&gt;]
  -h, --help                    Show this help message and exit.
  -o, --output=&lt;outputFolder&gt;   Output location full path.
  -V, --version                 Print version information and exit.</pre>
</div>
</div>
<div class="paragraph">
<p>The minimum value that can be specified for <code>longOptionsMaxWidth</code> is 20, the maximum value is the <a href="#_usage_width">usage width</a> minus <code>20</code>.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_ansi_colors_and_styles">14. ANSI Colors and Styles</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_colorized_example">14.1. Colorized Example</h3>
<div class="paragraph">
<p>Below shows the same usage help message as shown in <a href="#_expanded_example">Expanded Example</a>, with ANSI escape codes enabled.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/UsageHelpWithStyle.png" alt="Screenshot of usage help with Ansi codes enabled"></span></p>
</div>
</div>
<div class="sect2">
<h3 id="_usage_help_with_styles_and_colors">14.2. Usage Help with Styles and Colors</h3>
<div class="paragraph">
<p>You can use colors and styles in the descriptions, header and footer
of the usage help message.</p>
</div>
<div class="paragraph">
<p>Picocli supports a custom markup notation for mixing colors and styles in text,
following a convention introduced by <a href="https://github.com/fusesource/jansi">Jansi</a>, where
<code>@|</code> starts a styled section, and <code>|@</code> ends it.
Immediately following the <code>@|</code> is a comma-separated list of colors and styles, so <code>@|STYLE1[,STYLE2]&#8230;&#8203; text|@</code>.
For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Custom @|bold,underline styles|@ and @|fg(red) colors|@.</span><span class="delimiter">&quot;</span></span>)</code></pre>
</div>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/DescriptionWithColors.png" alt="Description with Ansi styles and colors"></span></p>
</div>
<table class="tableblock frame-all grid-cols stretch">
<caption class="title">Table 3. Pre-defined styles and colors that can be used in descriptions and headers using the <code>@|STYLE1[,STYLE2]&#8230;&#8203; text|@</code> notation</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Pre-defined Styles</th>
<th class="tableblock halign-left valign-top">Pre-defined Colors</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">bold</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">black</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">faint</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">red</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">underline</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">green</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">italic</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">yellow</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">blink</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">blue</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">reverse</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">magenta</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">reset</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">cyan</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">white</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>Colors are applied as <em>foreground</em> colors by default.
You can set <em>background</em> colors by specifying <code>bg(&lt;color&gt;)</code>.
For example, <code>@|bg(red) text with red background|@</code>.
Similarly, <code>fg(&lt;color&gt;)</code> explicitly sets the foreground color.</p>
</div>
<div class="paragraph">
<p>The example below shows how this markup can be used to add colors and styles to the headings and descriptions of a usage help message:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">commit</span><span class="delimiter">&quot;</span></span>,
        sortOptions = <span class="predefined-constant">false</span>,
        headerHeading = <span class="string"><span class="delimiter">&quot;</span><span class="content">@|bold,underline Usage|@:%n%n</span><span class="delimiter">&quot;</span></span>,
        synopsisHeading = <span class="string"><span class="delimiter">&quot;</span><span class="content">%n</span><span class="delimiter">&quot;</span></span>,
        descriptionHeading = <span class="string"><span class="delimiter">&quot;</span><span class="content">%n@|bold,underline Description|@:%n%n</span><span class="delimiter">&quot;</span></span>,
        parameterListHeading = <span class="string"><span class="delimiter">&quot;</span><span class="content">%n@|bold,underline Parameters|@:%n</span><span class="delimiter">&quot;</span></span>,
        optionListHeading = <span class="string"><span class="delimiter">&quot;</span><span class="content">%n@|bold,underline Options|@:%n</span><span class="delimiter">&quot;</span></span>,
        header = <span class="string"><span class="delimiter">&quot;</span><span class="content">Record changes to the repository.</span><span class="delimiter">&quot;</span></span>,
        description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Stores the current contents of the index in a new commit </span><span class="delimiter">&quot;</span></span> +
                <span class="string"><span class="delimiter">&quot;</span><span class="content">along with a log message from the user describing the changes.</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">GitCommit</span> { ... }</code></pre>
</div>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
Markup styles cannot be nested, for example: <code>@|bold this @|underline that|@|@</code> will not work. You can achieve the same by combining styles, for example: <code>@|bold this|@ @|bold,underline that|@</code> will work fine.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>From picocli 4.2, custom markup like <code>@|bold mytext|@</code>, <code>@|italic mytext|@</code> etc. can also be converted to custom markup like <code>&lt;b&gt;mytext&lt;/b&gt;</code> and <code>&lt;i&gt;mytext&lt;/i&gt;</code> in HTML, or <code>*mytext*</code> and <code>_mytext_</code> in lightweight markup languages like AsciiDoc.
Applications can control this by setting a <code>ColorScheme</code> with a custom markup map.
This feature is used to generate man page documentation.</p>
</div>
</div>
<div class="sect2">
<h3 id="_styles_and_colors_in_application_output">14.3. Styles and Colors in Application Output</h3>
<div class="paragraph">
<p>The use of ANSI colors and styles is not limited to the <a href="#_usage_help_with_styles_and_colors">usage help</a>
and <a href="#_static_version_information">version information</a>.</p>
</div>
<div class="paragraph">
<p>Applications can use the picocli <code>Ansi</code> class directly to create colored output.
By using the <code>Ansi.AUTO</code> enum value, picocli will  <a href="#_heuristics_for_enabling_ansi">auto-detect</a> whether it can emit ANSI escape codes or only the plain text.</p>
</div>
<div class="listingblock">
<div class="title">Using the picocli <code>Ansi</code> API to generate colored output.</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="comment">// import picocli.CommandLine.Help.Ansi;</span>
<span class="predefined-type">String</span> str = Ansi.AUTO.string(<span class="string"><span class="delimiter">&quot;</span><span class="content">@|bold,green,underline Hello, colored world!|@</span><span class="delimiter">&quot;</span></span>);
<span class="predefined-type">System</span>.out.println(str);</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_more_colors">14.4. More Colors</h3>
<div class="paragraph">
<p>Most terminals support a <a href="https://en.wikipedia.org/wiki/ANSI_escape_code#Colors">256 color indexed palette</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>0x00-0x07:  standard colors (the named colors)
0x08-0x0F:  high intensity colors (often similar to named colors + bold style)
0x10-0xE7:  6 × 6 × 6 cube (216 colors): 16 + 36 × r + 6 × g + b (0 ≤ r, g, b ≤ 5)
0xE8-0xFF:  grayscale from black to white in 24 steps</pre>
</div>
</div>
<div class="paragraph">
<p>Colors from the 256 color palette can be specified by their index values or by their RGB components.
RGB components must be separated by a semicolon <code>;</code> and each component must be between <code>0</code> and <code>5</code>, inclusive.</p>
</div>
<div class="paragraph">
<p>For example, <code>@|bg(0;5;0) text with red=0, green=5, blue=0 background|@</code>,
or <code>@|fg(46) the same color by index, as foreground color|@</code>.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/256colors.png" alt="256 color indexed palette"></span></p>
</div>
</div>
<div class="sect2">
<h3 id="_configuring_fixed_elements">14.5. Configuring Fixed Elements</h3>
<div class="sect3">
<h4 id="_color_scheme">14.5.1. Color Scheme</h4>
<div class="paragraph">
<p>Picocli uses a default color scheme for options, parameters and commands.
There are no annotations to modify this color scheme, but it can be changed programmatically.</p>
</div>
<div class="paragraph">
<p>The below code snippet shows how a custom color scheme can be specified to configure the usage help message style:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="comment">// see also CommandLine.Help.defaultColorScheme()</span>
ColorScheme colorScheme = <span class="keyword">new</span> ColorScheme()
        .commands    (<span class="predefined-type">Style</span>.bold, <span class="predefined-type">Style</span>.underline)    <span class="comment">// combine multiple styles</span>
        .options     (<span class="predefined-type">Style</span>.fg_yellow)                <span class="comment">// yellow foreground color</span>
        .parameters  (<span class="predefined-type">Style</span>.fg_yellow)
        .optionParams(<span class="predefined-type">Style</span>.italic);

CommandLine.usage(annotatedObject, <span class="predefined-type">System</span>.out, colorScheme);
...</code></pre>
</div>
</div>
<div class="paragraph">
<p>When using the <a href="#execute"><code>execute</code></a> API, you can configure a <code>ColorScheme</code> like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) {
    ColorScheme colorScheme = createColorScheme();

    <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MyApp())
            .setColorScheme(colorScheme) <span class="comment">// use this color scheme in the usage help message</span>
            .execute(args);
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_color_scheme_overrides">14.5.2. Color Scheme Overrides</h4>
<div class="paragraph">
<p>The following system properties override the color scheme styles. This allows end users to adjust for their individual terminal color setup.</p>
</div>
<div class="listingblock">
<div class="title">System Properties to Override the Color Scheme</div>
<div class="content">
<pre>picocli.color.commands
picocli.color.options
picocli.color.parameters
picocli.color.optionParams</pre>
</div>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>java -Dpicocli.color.options=blink,blue -Dpicocli.color.parameters=reverse com.app.Main</code></pre>
</div>
</div>
<div class="paragraph">
<p>System property values may specify multiple comma separated styles.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_supported_platforms">14.6. Supported Platforms</h3>
<div class="paragraph">
<p>Picocli will only emit ANSI escape codes on supported platforms.
For details, see <a href="#_heuristics_for_enabling_ansi">Heuristics for Enabling ANSI</a>.</p>
</div>
<div class="sect3">
<h4 id="_unix_and_linux">14.6.1. Unix and Linux</h4>
<div class="paragraph">
<p>Most Unix and Linux platforms support ANSI colors natively.
On Windows, when picocli detects it is running under a Unix variant like Cygwin or MSYS(2) on Windows
 it will display ANSI colors and styles, otherwise it will not emit ANSI codes.</p>
</div>
</div>
<div class="sect3">
<h4 id="_windows">14.6.2. Windows</h4>
<div class="paragraph">
<p>Displaying colors on Windows Command Console and PowerShell requires a bit of extra work.</p>
</div>
<div class="paragraph">
<p>The easiest way to accomplish this is to use the <a href="http://fusesource.github.io/jansi/">Jansi</a> library in your application.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
None of the below is mandatory. If not supported, picocli will simply not emit ANSI escape codes, and everything will work without colors.
</td>
</tr>
</table>
</div>
<div class="sect4">
<h5 id="_jansi">Jansi</h5>
<div class="paragraph">
<p>To use Jansi, you need to enable it in your application. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">org.fusesource.jansi.AnsiConsole</span>;
...
public <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) {
    AnsiConsole.systemInstall(); <span class="comment">// enable colors on Windows</span>
    <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> WindowsJansiDemo()).execute(args);
    AnsiConsole.systemUninstall(); <span class="comment">// cleanup when done</span>
}</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_jansi_in_graalvm_native_images">Jansi in GraalVM Native Images</h5>
<div class="paragraph">
<p>In Java applications compiled to a GraalVM native image for Windows, Jansi by itself is <a href="https://github.com/fusesource/jansi/issues/162">insufficient</a> to show colors.
This is partly because GraalVM requires configuration and partly because Jansi internally depends on non-standard system properties, without a graceful fallback if these properties are absent (as is the case in GraalVM).</p>
</div>
<div class="paragraph">
<p>Users may be interested in combining Jansi with <a href="https://github.com/remkop/picocli-jansi-graalvm">picocli-jansi-graalvm</a> until this issue is fixed. Example usage:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">picocli.jansi.graalvm.AnsiConsole</span>; <span class="comment">// not org.fusesource.jansi.AnsiConsole</span>
...
public <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) {
    <span class="type">int</span> exitCode;
    <span class="keyword">try</span> (AnsiConsole ansi = AnsiConsole.windowsInstall()) {
        exitCode = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MyApp()).execute(args);
    }
    <span class="predefined-type">System</span>.exit(exitCode);
}</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_for_reference_without_jansi_on_windows_10_command_console_and_powershell">For Reference: Without Jansi on Windows 10 Command Console and PowerShell</h5>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
As of this writing, the practical way to get colors in Command Console and PowerShell is to use Jansi. The below is just for reference.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Starting from Windows 10, the Windows Console <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/mt638032(v=vs.85).aspx">supports ANSI escape sequences</a>,
but <a href="https://github.com/Microsoft/WSL/issues/1173#issuecomment-254250445">it&#8217;s not enabled by default</a>.
Unless the specific software you&#8217;re using (e.g. java) enables ANSI processing by calling the <a href="https://docs.microsoft.com/en-us/windows/console/setconsolemode">SetConsoleMode</a> API with the <code>ENABLE_VIRTUAL_TERMINAL_PROCESSING</code> (<code>0x0400</code>) flag (java doesn&#8217;t), you won&#8217;t see colors or get ANSI processing for that application.</p>
</div>
<div class="paragraph">
<p>Note that there is a registry setting to <a href="https://superuser.com/questions/413073/windows-console-with-ansi-colors-handling/1300251#1300251">change the global default</a> from <em>opt in</em> to <em>opt out</em>.
This <a href="https://stackoverflow.com/a/51681675/1446916">Stack Overflow answer</a> has more details.</p>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
Note that picocli&#8217;s <a href="#_heuristics_for_enabling_ansi">heuristics for enabling ANSI</a> currently do not include detecting whether support for Virtual Terminal / ANSI escape sequences has been turned on or off via <code>SetConsoleMode</code> or a registry change.
So just making these changes is not sufficient to let a picocli-based application show colors.
Applications that enabled colors via <code>SetConsoleMode</code> may want to set system property <code>picocli.ansi</code> to <code>tty</code>.
Environments that enabled colors via a Windows Registry change may want to set environment variable <code>CLICOLOR=1</code>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="_for_reference_windows_subsystem_for_linux_wsl">For Reference: Windows Subsystem for Linux (WSL)</h5>
<div class="paragraph">
<p>You may want to recommend your users to try <a href="https://docs.microsoft.com/en-us/windows/wsl/install-win10">getting</a> <a href="https://docs.microsoft.com/en-us/windows/wsl/about">Windows Subsystem for Linux</a> (WSL).
This lets them run a GNU/Linux environment&#8201;&#8212;&#8201;including most command-line tools, utilities, and applications&#8201;&#8212;&#8201;directly on Windows, unmodified, without the overhead of a virtual machine.
Picocli-based applications will show ANSI colors in WSL by default.</p>
</div>
</div>
<div class="sect4">
<h5 id="_for_reference_3rd_party_software">For Reference: 3rd Party Software</h5>
<div class="paragraph">
<p>In Windows version prior to 10, the Windows command console doesn&#8217;t support output coloring by default.
One option is for end users to install either <a href="http://cmder.net/">Cmder</a>, <a href="http://sourceforge.net/projects/conemu/">ConEmu</a>, <a href="https://github.com/adoxa/ansicon/">ANSICON</a> or <a href="https://mintty.github.io/">Mintty</a> (used by default in GitBash and Cygwin) to add coloring support to their Windows command console.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_forcing_ansi_onoff">14.7. Forcing ANSI On/Off</h3>
<div class="paragraph">
<p>You can force picocli to either always use ANSI codes or never use ANSI codes regardless of the platform:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Setting system property <code>picocli.ansi</code> to <code>true</code> forces picocli to use ANSI codes; setting <code>picocli.ansi</code> to <code>false</code> forces picocli to <strong>not</strong> use ANSI codes. It may be useful for your users to mention this system property in the documentation for your command line application.</p>
</li>
<li>
<p>Setting system property <code>picocli.ansi</code> to <code>tty</code> (case-insensitive) forces picocli to use ANSI codes only if picocli guesses that the process is using an interactive console: either <code>System.console() != null</code> or picocli guesses the application is running in a pseudo-terminal pty on a Linux emulator in Windows. Otherwise the <a href="#_heuristics_for_enabling_ansi">below heuristics</a> are used to determine whether to output ANSI escape codes.</p>
</li>
<li>
<p>You can decide to force disable or force enable ANSI escape codes programmatically by specifying <code>Ansi.ON</code> or <code>Ansi.OFF</code> when invoking <code>CommandLine.usage</code>.
This overrides the value of system property <code>picocli.ansi</code>. For example:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">picocli.CommandLine.Help.Ansi</span>;

<span class="comment">// print usage help message to STDOUT without ANSI escape codes</span>
CommandLine.usage(<span class="keyword">new</span> App(), <span class="predefined-type">System</span>.out, Ansi.OFF);</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_heuristics_for_enabling_ansi">14.8. Heuristics for Enabling ANSI</h3>
<div class="paragraph">
<p>Below is the exact sequence of steps picocli uses to determine whether or not to emit ANSI escape codes.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>If <code>Ansi.ON</code> or <code>Ansi.OFF</code> is <a href="#_forcing_ansi_onoff">explicitly specified</a>, either via system property <code>picocli.ansi</code> or programmatically, this value is used.</p>
</li>
<li>
<p>ANSI is disabled when environment variable <a href="https://no-color.org/"><code>NO_COLOR</code></a> is defined (regardless of its value).</p>
</li>
<li>
<p>ANSI is enabled when environment variable <a href="https://bixense.com/clicolors/"><code>CLICOLOR_FORCE</code></a> is defined and has any value other than <code>0</code> (zero).</p>
</li>
<li>
<p>ANSI is enabled when system property <code>os.name</code> starts with <code>"Windows"</code> and JAnsi Console is <a href="https://github.com/fusesource/jansi">installed</a>.</p>
</li>
<li>
<p>ANSI is disabled when environment variable <a href="https://bixense.com/clicolors/"><code>CLICOLOR == 0</code></a>.</p>
</li>
<li>
<p>ANSI is disabled when environment variable <a href="https://conemu.github.io/en/AnsiEscapeCodes.html#Environment_variable"><code>ConEmuANSI == OFF</code></a>.</p>
</li>
<li>
<p>ANSI is disabled when Picocli <a href="https://stackoverflow.com/questions/1403772/how-can-i-check-if-a-java-programs-input-output-streams-are-connected-to-a-term"><em>guesses</em></a> the program&#8217;s output stream is not connected to a terminal: when <code>System.console()</code> returns <code>null</code>. This check is omitted if picocli <em>guesses</em> the program is running in a Windows <a href="https://www.cygwin.com/">Cygwin</a> or <a href="http://www.mingw.org/wiki/MSYS">MSYS</a> environment: when system property <code>os.name</code> starts with <code>"Windows"</code> and either environment variable <code>TERM</code> starts with <code>xterm</code> or environment variable <code>OSTYPE</code> is defined.</p>
</li>
<li>
<p>ANSI is enabled when environment variable <a href="https://github.com/adoxa/ansicon/blob/master/readme.txt"><code>ANSICON</code></a> is defined.</p>
</li>
<li>
<p>ANSI is enabled when environment variable <a href="https://bixense.com/clicolors/"><code>CLICOLOR == 1</code></a>.</p>
</li>
<li>
<p>ANSI is enabled when environment variable <a href="https://conemu.github.io/en/AnsiEscapeCodes.html#Environment_variable"><code>ConEmuANSI == ON</code></a>.</p>
</li>
<li>
<p>ANSI is enabled when picocli detects the program is running in a non-Windows OS (system property <code>os.name</code> does not start with <code>"Windows"</code>).</p>
</li>
<li>
<p>ANSI is enabled when picocli <em>guesses</em> the program is running in a <a href="https://www.cygwin.com/">Cygwin</a> or <a href="http://www.mingw.org/wiki/MSYS">MSYS</a> environment (either environment variable <code>TERM</code> starts with <code>xterm</code> or environment variable <code>OSTYPE</code> is defined).</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>ANSI escape codes are not emitted if none of the above apply.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_usage_help_api">15. Usage Help API</h2>
<div class="sectionbody">
<div class="paragraph">
<p>For further customization of the usage help message, picocli has a Help API.
The <code>Help</code> class provides a number of high-level operations, and a set of components like <code>Layout</code>, <code>TextTable</code>, <code>IOptionRenderer</code>, etc., that can be used to build custom help messages.
Details of the Help API are out of scope for this document, but the following sections give some idea of what is possible.</p>
</div>
<div class="sect2">
<h3 id="_reordering_sections">15.1. Reordering Sections</h3>
<div class="paragraph">
<p>One thing you may want to do is reorder sections of the usage message or add custom sections.</p>
</div>
<div class="paragraph">
<p>Picocli 3.9 introduces new API to facilitate customizing the usage help message:
<code>IHelpFactory</code> allows applications to plug in <code>Help</code> subclasses, and
<code>IHelpSectionRenderer</code> allows applications to add custom sections to the usage help message, or redefine existing sections.</p>
</div>
<div class="paragraph">
<p>The usage help message is no longer hard-coded, but is now constructed from the section renderers defined in <code>CommandLine::getHelpSectionMap</code> (or <code>UsageMessageSpec::sectionMap</code> for a single <code>CommandSpec</code>).
By default this map contains the predefined section renderers:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="comment">// The default section renderers delegate to methods in Help for their implementation</span>
<span class="comment">// (using Java 8 lambda notation for brevity):</span>
<span class="predefined-type">Map</span>&lt;<span class="predefined-type">String</span>, IHelpSectionRenderer&gt; map = <span class="keyword">new</span> <span class="predefined-type">HashMap</span>&lt;&gt;();
map.put(SECTION_KEY_HEADER_HEADING,         help -&gt; help.headerHeading());
map.put(SECTION_KEY_HEADER,                 help -&gt; help.header());

<span class="comment">//e.g. Usage:</span>
map.put(SECTION_KEY_SYNOPSIS_HEADING,       help -&gt; help.synopsisHeading());

<span class="comment">//e.g. &lt;cmd&gt; [OPTIONS] &lt;subcmd&gt; [COMMAND-OPTIONS] [ARGUMENTS]</span>
map.put(SECTION_KEY_SYNOPSIS,               help -&gt; help.synopsis(help.synopsisHeadingLength()));

<span class="comment">//e.g. %nDescription:%n%n</span>
map.put(SECTION_KEY_DESCRIPTION_HEADING,    help -&gt; help.descriptionHeading());

<span class="comment">//e.g. {&quot;Converts foos to bars.&quot;, &quot;Use options to control conversion mode.&quot;}</span>
map.put(SECTION_KEY_DESCRIPTION,            help -&gt; help.description());

<span class="comment">//e.g. %nPositional parameters:%n%n</span>
map.put(SECTION_KEY_PARAMETER_LIST_HEADING, help -&gt; help.parameterListHeading());

<span class="comment">//e.g. [FILE...] the files to convert</span>
map.put(SECTION_KEY_PARAMETER_LIST,         help -&gt; help.parameterList());

<span class="comment">//e.g. %nOptions:%n%n</span>
map.put(SECTION_KEY_OPTION_LIST_HEADING,    help -&gt; help.optionListHeading());

<span class="comment">//e.g. -h, --help   displays this help and exits</span>
map.put(SECTION_KEY_OPTION_LIST,            help -&gt; help.optionList());

<span class="comment">//e.g. %nCommands:%n%n</span>
map.put(SECTION_KEY_COMMAND_LIST_HEADING,   help -&gt; help.commandListHeading());

<span class="comment">//e.g.    add       this command adds the frup to the frooble</span>
map.put(SECTION_KEY_COMMAND_LIST,           help -&gt; help.commandList());
map.put(SECTION_KEY_EXIT_CODE_LIST_HEADING, help -&gt; help.exitCodeListHeading());
map.put(SECTION_KEY_EXIT_CODE_LIST,         help -&gt; help.exitCodeList());
map.put(SECTION_KEY_FOOTER_HEADING,         help -&gt; help.footerHeading());
map.put(SECTION_KEY_FOOTER,                 help -&gt; help.footer());</code></pre>
</div>
</div>
<div class="paragraph">
<p>Applications can add, remove or replace sections in this map. The <code>CommandLine::getHelpSectionKeys</code> method (or <code>UsageMessageSpec::sectionKeys</code> for a single <code>CommandSpec</code>) returns the section keys in the order that the usage help message should render the sections. The default keys are (in order):</p>
</div>
<div class="olist arabic">
<ol class="arabic" start="0">
<li>
<p>SECTION_KEY_HEADER_HEADING</p>
</li>
<li>
<p>SECTION_KEY_HEADER</p>
</li>
<li>
<p>SECTION_KEY_SYNOPSIS_HEADING</p>
</li>
<li>
<p>SECTION_KEY_SYNOPSIS</p>
</li>
<li>
<p>SECTION_KEY_DESCRIPTION_HEADING</p>
</li>
<li>
<p>SECTION_KEY_DESCRIPTION</p>
</li>
<li>
<p>SECTION_KEY_PARAMETER_LIST_HEADING</p>
</li>
<li>
<p>SECTION_KEY_AT_FILE_PARAMETER</p>
</li>
<li>
<p>SECTION_KEY_PARAMETER_LIST</p>
</li>
<li>
<p>SECTION_KEY_OPTION_LIST_HEADING</p>
</li>
<li>
<p>SECTION_KEY_OPTION_LIST</p>
</li>
<li>
<p>SECTION_KEY_COMMAND_LIST_HEADING</p>
</li>
<li>
<p>SECTION_KEY_COMMAND_LIST</p>
</li>
<li>
<p>SECTION_KEY_EXIT_CODE_LIST_HEADING</p>
</li>
<li>
<p>SECTION_KEY_EXIT_CODE_LIST</p>
</li>
<li>
<p>SECTION_KEY_FOOTER_HEADING</p>
</li>
<li>
<p>SECTION_KEY_FOOTER</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>This ordering may be modified with the <code>CommandLine::setHelpSectionKeys</code> setter method (or <code>UsageMessageSpec::sectionKeys(List)</code> for a single <code>CommandSpec</code>).</p>
</div>
<div class="sect3">
<h4 id="_custom_help_section_example">15.1.1. Custom Help Section Example</h4>
<div class="paragraph">
<p>The below example shows how to add a custom Environment Variables section to the usage help message.</p>
</div>
<div class="listingblock">
<div class="title">Adding a custom Environment Variables section</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="comment">// help section keys</span>
<span class="directive">static</span> <span class="directive">final</span> <span class="predefined-type">String</span> SECTION_KEY_ENV_HEADING = <span class="string"><span class="delimiter">&quot;</span><span class="content">environmentVariablesHeading</span><span class="delimiter">&quot;</span></span>;
<span class="directive">static</span> <span class="directive">final</span> <span class="predefined-type">String</span> SECTION_KEY_ENV_DETAILS = <span class="string"><span class="delimiter">&quot;</span><span class="content">environmentVariables</span><span class="delimiter">&quot;</span></span>;
<span class="comment">// ...</span>

<span class="comment">// the data to display</span>
<span class="predefined-type">Map</span>&lt;<span class="predefined-type">String</span>, <span class="predefined-type">String</span>&gt; env = <span class="keyword">new</span> <span class="predefined-type">LinkedHashMap</span>&lt;&gt;();
env.put(<span class="string"><span class="delimiter">&quot;</span><span class="content">FOO</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">explanation of foo</span><span class="delimiter">&quot;</span></span>);
env.put(<span class="string"><span class="delimiter">&quot;</span><span class="content">BAR</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">explanation of bar</span><span class="delimiter">&quot;</span></span>);
env.put(<span class="string"><span class="delimiter">&quot;</span><span class="content">XYZ</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">xxxx yyyy zzz</span><span class="delimiter">&quot;</span></span>);

<span class="comment">// register the custom section renderers</span>
CommandLine cmd = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MyApp());
cmd.getHelpSectionMap().put(SECTION_KEY_ENV_HEADING,
                            help -&gt; help.createHeading(<span class="string"><span class="delimiter">&quot;</span><span class="content">Environment Variables:%n</span><span class="delimiter">&quot;</span></span>));
cmd.getHelpSectionMap().put(SECTION_KEY_ENV_DETAILS,
                            help -&gt; help.createTextTable(env).toString());

<span class="comment">// specify the location of the new sections</span>
<span class="predefined-type">List</span>&lt;<span class="predefined-type">String</span>&gt; keys = <span class="keyword">new</span> <span class="predefined-type">ArrayList</span>&lt;&gt;(cmd.getHelpSectionKeys());
<span class="type">int</span> index = keys.indexOf(CommandLine.Model.UsageMessageSpec.SECTION_KEY_FOOTER_HEADING);
keys.add(index, SECTION_KEY_ENV_HEADING);
keys.add(index + <span class="integer">1</span>, SECTION_KEY_ENV_DETAILS);
cmd.setHelpSectionKeys(keys);</code></pre>
</div>
</div>
<div class="paragraph">
<p>More examples for customizing the usage help message are <a href="https://github.com/remkop/picocli/tree/master/picocli-examples/src/main/java/picocli/examples/customhelp">here</a>.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_custom_layout">15.2. Custom Layout</h3>
<div class="paragraph">
<p>Picocli also supports unconventional option list layouts. An example of an unconventional layout is the <code>zip</code> application, which shows multiple options per row:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">CommandLine.usage(<span class="keyword">new</span> ZipHelpDemo(), <span class="predefined-type">System</span>.out);</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre>Copyright (c) 1990-2008 Info-ZIP - Type 'zip "-L"' for software license.
Zip 3.0 (July 5th 2008). Command:
zip [-options] [-b path] [-t mmddyyyy] [-n suffixes] [zipfile list] [-xi list]
  The default action is to add or replace zipfile entries from list, which
  can include the special name - to compress standard input.
  If zipfile and list are omitted, zip compresses stdin to stdout.
  -f   freshen: only changed files  -u   update: only changed or new files
  -d   delete entries in zipfile    -m   move into zipfile (delete OS files)
  -r   recurse into directories     -j   junk (don't record) directory names
  -0   store only                   -l   convert LF to CR LF (-ll CR LF to LF)
  -1   compress faster              -9   compress better
  -q   quiet operation              -v   verbose operation/print version info
  -c   add one-line comments        -z   add zipfile comment
  -@   read names from stdin        -o   make zipfile as old as latest entry
  -x   exclude the following names  -i   include only the following names
  -F   fix zipfile (-FF try harder) -D   do not add directory entries
  -A   adjust self-extracting exe   -J   junk zipfile prefix (unzipsfx)
  -T   test zipfile integrity       -X   eXclude eXtra file attributes
  -y   store symbolic links as the link instead of the referenced file
  -e   encrypt                      -n   don't compress these suffixes
  -h2  show more help</pre>
</div>
</div>
<div class="paragraph">
<p>This can be achieved in picocli by subclassing the Help.Layout class.
See the <a href="https://github.com/remkop/picocli/blob/master/src/test/java/picocli/CustomLayoutDemo.java">CustomLayoutDemo</a> class in the picocli tests for how to achieve this.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_subcommands">16. Subcommands</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_registering_subcommands_declaratively">16.1. Registering Subcommands Declaratively</h3>
<div class="paragraph">
<p>From v0.9.8, picocli supports registering subcommands declaratively with the <code>@Command</code> annotation&#8217;s <code>subcommands</code> attribute.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(subcommands = {
    GitStatus.class,
    GitCommit.class,
    GitAdd.class,
    GitBranch.class,
    GitCheckout.class,
    GitClone.class,
    GitDiff.class,
    GitMerge.class,
    GitPush.class,
    GitRebase.class,
    GitTag.class
})
<span class="directive">public</span> <span class="type">class</span> <span class="class">Git</span> { ... }</code></pre>
</div>
</div>
<div class="paragraph">
<p>Subcommands referenced in a <code>subcommands</code> attribute <em>must</em> have a <code>@Command</code> annotation with a <code>name</code> attribute, or an exception is thrown from the <code>CommandLine</code> constructor. This name will be used both for generating usage help and for recognizing subcommands when parsing the command line.</p>
</div>
<div class="paragraph">
<p>Custom type converters registered on a <code>CommandLine</code> instance will apply to all subcommands that were declared on the main command with the <code>subcommands</code> annotation.</p>
</div>
<div class="paragraph">
<p>Subcommands referenced in a <code>subcommands</code> attribute need to have a public no-argument constructor to be instantiated, unless a <a href="#_custom_factory">Custom Factory</a> is installed to instantiate classes.</p>
</div>
<div class="paragraph">
<p>Prior to picocli 4,2, the declared subcommands were instantiated immediately when the top-level <code>CommandLine</code> (the <code>new CommandLine(new Git())</code> object in the above example) was constructed.</p>
</div>
<div class="paragraph">
<p>From picocli 4.2, the declared subcommands are not instantiated until they are matched on the command line, unless they have a <code>@Spec</code> or <code>@ParentObject</code>-annotated field; these are injected during initialization, and in order to inject them the subcommand is instantiated during initialization.</p>
</div>
</div>
<div class="sect2">
<h3 id="_registering_subcommands_programmatically">16.2. Registering Subcommands Programmatically</h3>
<div class="paragraph">
<p>Subcommands can be registered with the <code>CommandLine.addSubcommand</code> method.
You pass in the name of the command and the annotated object to populate with the subcommand options.
The specified name is used by the parser to recognize subcommands in the command line arguments.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">CommandLine commandLine = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> Git())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">status</span><span class="delimiter">&quot;</span></span>,   <span class="keyword">new</span> GitStatus())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">commit</span><span class="delimiter">&quot;</span></span>,   <span class="keyword">new</span> GitCommit())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">add</span><span class="delimiter">&quot;</span></span>,      <span class="keyword">new</span> GitAdd())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">branch</span><span class="delimiter">&quot;</span></span>,   <span class="keyword">new</span> GitBranch())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">checkout</span><span class="delimiter">&quot;</span></span>, <span class="keyword">new</span> GitCheckout())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">clone</span><span class="delimiter">&quot;</span></span>,    <span class="keyword">new</span> GitClone())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">diff</span><span class="delimiter">&quot;</span></span>,     <span class="keyword">new</span> GitDiff())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">merge</span><span class="delimiter">&quot;</span></span>,    <span class="keyword">new</span> GitMerge())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">push</span><span class="delimiter">&quot;</span></span>,     <span class="keyword">new</span> GitPush())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">rebase</span><span class="delimiter">&quot;</span></span>,   <span class="keyword">new</span> GitRebase())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">tag</span><span class="delimiter">&quot;</span></span>,      <span class="keyword">new</span> GitTag());</code></pre>
</div>
</div>
<div class="paragraph">
<p>It is strongly recommended that subcommands have a <code>@Command</code> annotation with <code>name</code> and <code>description</code> attributes.</p>
</div>
<div class="paragraph">
<p>From picocli 3.1, the usage help synopsis of the subcommand shows not only the subcommand name but also the parent command name.
For example, if the <code>git</code> command has a <code>commit</code> subcommand, the usage help for the <code>commit</code> subcommand shows <code>Usage: git commit &lt;options&gt;</code>.</p>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
<em>Note on custom type converters:</em> custom type converters are registered only with the subcommands and nested
sub-subcommands that were added <em>before</em> the custom type was registered.
To ensure a custom type converter is available to all subcommands, register the type converter last, after
adding subcommands.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_subcommand_aliases">16.3. Subcommand Aliases</h3>
<div class="paragraph">
<p>Commands may optionally define an <code>aliases</code> attribute to provide alternate names for commands that will be recognized by the parser. Aliases are displayed in the default help output. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">status</span><span class="delimiter">&quot;</span></span>, aliases = {<span class="string"><span class="delimiter">&quot;</span><span class="content">st</span><span class="delimiter">&quot;</span></span>}, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Show the working tree status.</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">GitStatus</span> { ... }</code></pre>
</div>
</div>
<div class="paragraph">
<p>Would result in this help fragment:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>status, st    Show the working tree status.</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_subcommands_as_methods">16.4. Subcommands as Methods</h3>
<div class="paragraph">
<p>As of picocli 3.6 it is possible to register subcommands in a very compact manner by having a <code>@Command</code> class with <code>@Command</code>-annotated methods. The methods are automatically <a href="#_subcommand_methods">registered as subcommands</a> of the <code>@Command</code> class.</p>
</div>
<div class="paragraph">
<p>The <a href="https://github.com/remkop/picocli/blob/master/picocli-examples"><code>picocli-examples</code></a> module has an  minimal example application, demonstrating the definition of subcommands via methods. This example was coded in <a href="https://github.com/remkop/picocli/blob/master/picocli-examples/src/main/java/picocli/examples/subcommands/SubCmdsViaMethods.java">Java</a>, <a href="https://github.com/remkop/picocli/blob/master/picocli-examples/src/main/kotlin/picocli/examples/kotlin/subcommands/SubCmdsViaMethods.kt">Kotlin</a> and <a href="https://github.com/remkop/picocli/blob/master/picocli-examples/src/main/scala/picocli/examples/scala/subcommands/SubCmdsViaMethods.scala">Scala</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_executing_subcommands">16.5. Executing Subcommands</h3>
<div class="paragraph">
<p>The easiest way to design an application with subcommands is to let each command and subcommand either be a class that implements <code>Runnable</code> or <code>Callable</code>, or a <code>@Command</code>-annotated method.</p>
</div>
<div class="paragraph">
<p>This will allow you to parse the command line, deal with requests for help and requests for version information, deal with invalid user input, and invoke the business logic of the user-specified subcommand - all of that - in one line of code: the <a href="#execute"><code>execute</code></a> method.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">foo</span><span class="delimiter">&quot;</span></span>, subcommands = Bar.class)
<span class="type">class</span> <span class="class">Foo</span> <span class="directive">implements</span> <span class="predefined-type">Callable</span>&lt;<span class="predefined-type">Integer</span>&gt; {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>) <span class="type">int</span> x;

    <span class="annotation">@Override</span> <span class="directive">public</span> <span class="predefined-type">Integer</span> call() {
        <span class="predefined-type">System</span>.out.printf(<span class="string"><span class="delimiter">&quot;</span><span class="content">hi from foo, x=%d%n</span><span class="delimiter">&quot;</span></span>, x);
        <span class="type">boolean</span> ok = <span class="predefined-constant">true</span>;
        <span class="keyword">return</span> ok ? <span class="integer">0</span> : <span class="integer">1</span>; <span class="comment">// exit code</span>
    }

    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span>... args) {
        <span class="type">int</span> exitCode = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> Foo()).execute(args);
        <span class="predefined-type">System</span>.exit(exitCode);
    }
}

<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">bar</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">I'm a subcommand of `foo`</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">Bar</span> <span class="directive">implements</span> <span class="predefined-type">Callable</span>&lt;<span class="predefined-type">Integer</span>&gt; {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-y</span><span class="delimiter">&quot;</span></span>) <span class="type">int</span> y;

    <span class="annotation">@Override</span> <span class="directive">public</span> <span class="predefined-type">Integer</span> call() {
        <span class="predefined-type">System</span>.out.printf(<span class="string"><span class="delimiter">&quot;</span><span class="content">hi from bar, y=%d%n</span><span class="delimiter">&quot;</span></span>, y);
        <span class="keyword">return</span> <span class="integer">23</span>;
    }

    <span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">baz</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">I'm a subcommand of `bar`</span><span class="delimiter">&quot;</span></span>)
    <span class="type">int</span> baz(<span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-z</span><span class="delimiter">&quot;</span></span>) <span class="type">int</span> z) {
        <span class="predefined-type">System</span>.out.printf(<span class="string"><span class="delimiter">&quot;</span><span class="content">hi from baz, z=%d%n</span><span class="delimiter">&quot;</span></span>, z);
        <span class="keyword">return</span> <span class="integer">45</span>;
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>To test our example on Linux, we created an alias <code>foo</code> that invokes our Java application. This could also be a script or a function that calls our Java program:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">alias foo='java Foo'</code></pre>
</div>
</div>
<div class="paragraph">
<p>Next, we call our top-level command with an option like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ foo -x 123
hi from foo, x=123

#check the exit code
$ echo $?
0</code></pre>
</div>
</div>
<div class="paragraph">
<p>We can also specify a subcommand:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ foo -x 123 bar -y=456
hi from bar, y=456

#check the exit code
$ echo $?
23</code></pre>
</div>
</div>
<div class="paragraph">
<p>And finally, we can also specify a sub-subcommand:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">$ foo bar baz -z=789
hi from baz, z=789

#check the exit code
$ echo $?
45</code></pre>
</div>
</div>
<div class="paragraph">
<p>As you can see, the <em>last specified</em> command or subcommand is executed and its exit code is returned.
See also <a href="#_executing_commands_with_subcommands">Executing Commands with Subcommands</a> for details on configuring this.</p>
</div>
</div>
<div class="sect2">
<h3 id="_initialization_before_execution">16.6. Initialization Before Execution</h3>
<div class="paragraph">
<p>Sometimes an application needs to take some action before execution.
With a single command, you can simply do this in the beginning of the <code>run</code> or <code>call</code> method, but in an application with subcommands you don&#8217;t want to repeat this code in every subcommand.</p>
</div>
<div class="paragraph">
<p>One idea is to put the shared initialization logic in a custom execution strategy. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(subcommands = {Sub1.class, Sub2.class, Sub3.class})
<span class="type">class</span> <span class="class">MyApp</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span> {

    <span class="comment">// A reference to this method can be used as a custom execution strategy</span>
    <span class="comment">// that first calls the init() method,</span>
    <span class="comment">// and then delegates to the default execution strategy.</span>
    <span class="directive">private</span> <span class="type">int</span> executionStrategy(ParseResult parseResult) {
        init(); <span class="comment">// custom initialization to be done before executing any command or subcommand</span>
        <span class="keyword">return</span> <span class="keyword">new</span> CommandLine.RunLast().execute(parseResult); <span class="comment">// default execution strategy</span>
    }

    <span class="directive">private</span> <span class="type">void</span> init() {
        <span class="comment">// ...</span>
    }

    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) {
        MyApp app = <span class="keyword">new</span> MyApp();
        <span class="keyword">new</span> CommandLine(app)
                .setExecutionStrategy(app::executionStrategy)
                .execute(args);
    }

    <span class="comment">//...</span>
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This ensures the <code>init</code> method is called <em>after</em> the command line is parsed (so all options and positional parameters are assigned) but <em>before</em> the user-specified subcommand is executed.</p>
</div>
</div>
<div class="sect2">
<h3 id="_manually_parsing_subcommands">16.7. Manually Parsing Subcommands</h3>
<div class="paragraph">
<p>For the following example, we assume we created an alias <code>git</code> that invokes our Java application. This could also be a script or a function that calls our Java program:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">alias git='java picocli.Demo$Git'</code></pre>
</div>
</div>
<div class="paragraph">
<p>Next, we call our command with some arguments like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">git --git-dir=/home/rpopma/picocli status -sb -uno</code></pre>
</div>
</div>
<div class="paragraph">
<p>Where <code>git</code> (actually <code>java picocli.Demo$Git</code>) is the top-level command, followed by a global option and a subcommand <code>status</code> with its own options.</p>
</div>
<div class="paragraph">
<p>Setting up the parser and parsing the command line could look like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span>... args) {
    <span class="comment">// Set up the parser</span>
    CommandLine commandLine = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> Git());

    <span class="comment">// add subcommands programmatically (not necessary if the parent command</span>
    <span class="comment">// declaratively registers the subcommands via annotation)</span>
    commandLine.addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">status</span><span class="delimiter">&quot;</span></span>,   <span class="keyword">new</span> GitStatus())
               .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">commit</span><span class="delimiter">&quot;</span></span>,   <span class="keyword">new</span> GitCommit())
                ...

    <span class="comment">// Invoke the parseArgs method to parse the arguments</span>
    ParseResult parsed = commandLine.parseArgs(args);
    handleParseResult(parsed);
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>CommandLine.parseArgs</code> method returns a <code>ParseResult</code> that can be queried to get information about
the top-level command (the Java class invoked by <code>git</code> in this example).
The <code>ParseResult.subcommand()</code> method returns a nested <code>ParseResult</code> if the parser found a subcommand.
This can be recursively queried until the last nested subcommand was found and the <code>ParseResult.subcommand()</code> method returns <code>null</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">private</span> <span class="type">void</span> handleParseResult(ParseResult parsed) {
    <span class="keyword">assert</span> parsed.subcommand() != <span class="predefined-constant">null</span> : <span class="string"><span class="delimiter">&quot;</span><span class="content">at least 1 command and 1 subcommand found</span><span class="delimiter">&quot;</span></span>

    ParseResult sub = parsed.subcommand();
    <span class="keyword">assert</span> parsed.commandSpec().userObject().getClass() == Git.class       : <span class="string"><span class="delimiter">&quot;</span><span class="content">main command</span><span class="delimiter">&quot;</span></span>
    <span class="keyword">assert</span>    sub.commandSpec().userObject().getClass() == GitStatus.class : <span class="string"><span class="delimiter">&quot;</span><span class="content">subcommand</span><span class="delimiter">&quot;</span></span>

    Git git = (Git) parsed.commandSpec().userObject();
    <span class="keyword">assert</span> git.gitDir.equals(<span class="keyword">new</span> <span class="predefined-type">File</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">/home/rpopma/picocli</span><span class="delimiter">&quot;</span></span>));

    GitStatus gitstatus = (GitStatus) sub.commandSpec().userObject();
    <span class="keyword">assert</span>  gitstatus.shortFormat              : <span class="string"><span class="delimiter">&quot;</span><span class="content">git status -s</span><span class="delimiter">&quot;</span></span>
    <span class="keyword">assert</span>  gitstatus.branchInfo               : <span class="string"><span class="delimiter">&quot;</span><span class="content">git status -b</span><span class="delimiter">&quot;</span></span>
    <span class="keyword">assert</span> !gitstatus.showIgnored              : <span class="string"><span class="delimiter">&quot;</span><span class="content">git status --showIgnored not specified</span><span class="delimiter">&quot;</span></span>
    <span class="keyword">assert</span>  gitstatus.mode == GitStatusMode.no : <span class="string"><span class="delimiter">&quot;</span><span class="content">git status -u=no</span><span class="delimiter">&quot;</span></span>
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You may be interested in the <a href="#execute">execute method</a> to reduce error handling and other boilerplate code in your application.
See also the previous section, <a href="#_executing_subcommands">Executing Subcommands</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="parentcommand-annotation">16.8. <code>@ParentCommand</code> Annotation</h3>
<div class="paragraph">
<p>In command line applications with subcommands, options of the top level command are often intended as "global" options that apply to all the subcommands. Prior to picocli 2.2, subcommands had no easy way to access their parent command options unless the parent command made these values available in a global variable.</p>
</div>
<div class="paragraph">
<p>The <code>@ParentCommand</code> annotation introduced in picocli 2.2 makes it easy for subcommands to access their parent command options: subcommand fields annotated with <code>@ParentCommand</code> are initialized with a reference to the parent command. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">fileutils</span><span class="delimiter">&quot;</span></span>, subcommands = <span class="predefined-type">List</span>.class)
<span class="type">class</span> <span class="class">FileUtils</span> {

    <span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-d</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--directory</span><span class="delimiter">&quot;</span></span>},
            description = <span class="string"><span class="delimiter">&quot;</span><span class="content">this option applies to all subcommands</span><span class="delimiter">&quot;</span></span>)
    <span class="predefined-type">File</span> baseDirectory;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above top-level command has a <code>--directory</code> option that applies to its subcommands.
The <code>List</code> subcommand can use the <code>@ParentCommand</code> annotation to get a reference to the parent command, so it can easily access the parent command options.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">list</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">List</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span> {

    <span class="annotation">@ParentCommand</span>
    <span class="directive">private</span> FileUtils parent; <span class="comment">// picocli injects reference to parent command</span>

    <span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-r</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--recursive</span><span class="delimiter">&quot;</span></span>},
            description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Recursively list subdirectories</span><span class="delimiter">&quot;</span></span>)
    <span class="directive">private</span> <span class="type">boolean</span> recursive;

    <span class="annotation">@Override</span>
    <span class="directive">public</span> <span class="type">void</span> run() {
        list(<span class="keyword">new</span> <span class="predefined-type">File</span>(parent.baseDirectory, <span class="string"><span class="delimiter">&quot;</span><span class="content">.</span><span class="delimiter">&quot;</span></span>));
    }

    <span class="directive">private</span> <span class="type">void</span> list(<span class="predefined-type">File</span> dir) {
        <span class="predefined-type">System</span>.out.println(dir.getAbsolutePath());
        <span class="keyword">if</span> (dir.isDirectory()) {
            <span class="keyword">for</span> (<span class="predefined-type">File</span> f : dir.listFiles()) {
                <span class="keyword">if</span> (f.isDirectory() &amp;&amp; recursive) {
                    list(f);
                } <span class="keyword">else</span> {
                    <span class="predefined-type">System</span>.out.println(f.getAbsolutePath());
                }
            }
        }
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_nested_sub_subcommands">16.9. Nested sub-Subcommands</h3>
<div class="paragraph">
<p>The specified object can be an annotated object or a
<code>CommandLine</code> instance with its own nested subcommands. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">CommandLine commandLine = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MainCommand())
    .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">cmd1</span><span class="delimiter">&quot;</span></span>,                 <span class="keyword">new</span> ChildCommand1())
    .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">cmd2</span><span class="delimiter">&quot;</span></span>,                 <span class="keyword">new</span> ChildCommand2())
    .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">cmd3</span><span class="delimiter">&quot;</span></span>, <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> ChildCommand3())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">cmd3sub1</span><span class="delimiter">&quot;</span></span>,                 <span class="keyword">new</span> GrandChild3Command1())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">cmd3sub2</span><span class="delimiter">&quot;</span></span>,                 <span class="keyword">new</span> GrandChild3Command2())
        .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">cmd3sub3</span><span class="delimiter">&quot;</span></span>, <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> GrandChild3Command3())
            .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">cmd3sub3sub1</span><span class="delimiter">&quot;</span></span>, <span class="keyword">new</span> GreatGrandChild3Command3_1())
            .addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">cmd3sub3sub2</span><span class="delimiter">&quot;</span></span>, <span class="keyword">new</span> GreatGrandChild3Command3_2())
        )
    );</code></pre>
</div>
</div>
<div class="paragraph">
<p>Declaratively, subcommands can be nested by specifying the <code>subcommands</code> attribute on subcommand classes:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">main</span><span class="delimiter">&quot;</span></span>, subcommands = {
    ChildCommand1.class,
    ChildCommand2.class,
    ChildCommand3.class })
<span class="type">class</span> <span class="class">MainCommand</span> { }

<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">cmd3</span><span class="delimiter">&quot;</span></span>, subcommands = {
    GrandChild3Command1.class,
    GrandChild3Command2.class,
    GrandChild3Command3.class })
<span class="type">class</span> <span class="class">ChildCommand3</span> { }

<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">cmd3sub3</span><span class="delimiter">&quot;</span></span>, subcommands = {
    GreatGrandChild3Command3_1.class,
    GreatGrandChild3Command3_2.class })
<span class="type">class</span> <span class="class">GrandChild3Command3</span> { }
...</code></pre>
</div>
</div>
<div class="paragraph">
<p>By default, the usage help message only shows the subcommands of the specified command,
and not the nested sub-subcommands. This can be customized by specifying your own <a href="#_reordering_sections"><code>IHelpSectionRenderer</code></a> for the command list section.
The <code>picocli-examples</code> module has an <a href="https://github.com/remkop/picocli/blob/master/picocli-examples/src/main/java/picocli/examples/customhelp/ShowCommandHierarchy.java">example</a> that shows how to accomplish this.</p>
</div>
</div>
<div class="sect2">
<h3 id="_repeatable_subcommands">16.10. Repeatable Subcommands</h3>
<div class="paragraph">
<p>From picocli 4.2, it is possible to specify that a command&#8217;s subcommands can be specified multiple times by marking it with <code>@Command(subcommandsRepeatable = true)</code>.</p>
</div>
<div class="sect3">
<h4 id="_example_3">16.10.1. Example</h4>
<div class="paragraph">
<p>Below is an example where the top-level command <code>myapp</code> is marked as <code>subcommandsRepeatable = true</code>.
This command has three subcommands, <code>add</code>, <code>list</code> and <code>send-report</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">myapp</span><span class="delimiter">&quot;</span></span>, subcommandsRepeatable = <span class="predefined-constant">true</span>)
<span class="type">class</span> <span class="class">MyApp</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span> {

    <span class="annotation">@Command</span>
    <span class="type">void</span> add(<span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>) <span class="predefined-type">String</span> x, <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-w</span><span class="delimiter">&quot;</span></span>) <span class="type">double</span> w) { ... }

    <span class="annotation">@Command</span>
    <span class="type">void</span> list(<span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">--where</span><span class="delimiter">&quot;</span></span>) <span class="predefined-type">String</span> where) { ... }

    <span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">send-report</span><span class="delimiter">&quot;</span></span>)
    <span class="type">void</span> sendReport(<span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">--to</span><span class="delimiter">&quot;</span></span>, split = <span class="string"><span class="delimiter">&quot;</span><span class="content">,</span><span class="delimiter">&quot;</span></span>) <span class="predefined-type">String</span><span class="type">[]</span> recipients) { ... }

    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span>... args) {
        <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MyApp()).execute(args);
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above example command allows users to specify one or more of its subcommands multiple time. For example, this would be a valid invocation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash">myapp add -x=item1 -w=0.2 \
      add -x=item2 -w=0.5 \
      add -x=item3 -w=0.7 \
      list --where &quot;w&gt;0.2&quot; \
      send-report --to=recipient@myorg.com</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the above command line invocation, the <code>myapp</code> top-level command is followed by its subcommand <code>add</code>.
Next, this is followed by another two occurences of <code>add</code>, followed by <code>list</code> and <code>send-report</code>.
These are all "sibling" commands, that share the same parent command <code>myapp</code>.
This invocation is valid because <code>myapp</code> is marked with <code>subcommandsRepeatable = true</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_repeatable_subcommands_specification">16.10.2. Repeatable Subcommands Specification</h4>
<div class="paragraph">
<p>Normally, <code>subcommandsRepeatable</code> is <code>false</code>, so for each command, only one of its subcommands can be specified, potentially followed by only one sub-subcommand of that subcommand, etc.
In mathematical terms, a valid sequence of commands and subcommands can be represented by a <em>directed rooted tree</em> that starts at the top-level command. This is illustrated by the diagram below.</p>
</div>
<div id="sequences-when-subcommands-not-repeatable" class="imageblock">
<div class="content">
<img src="images/subcommands-non-repeatable.png" alt="subcommands non repeatable">
</div>
<div class="title">Figure 1. By default, valid sequences of commands and subcommands form a directed rooted tree.</div>
</div>
<div class="paragraph">
<p>When <code>subcommandsRepeatable</code> is set to <code>true</code> on a command, the subcommands of this command may appear multiple times.
Also, a subcommand can be followed by a "sibling" command (another command with the same parent command).</p>
</div>
<div class="paragraph">
<p>In mathematical terms, when a parent command has this property, the additional valid sequences of its subcommands form a fully connected subgraph (<em>a complete digraph</em>).</p>
</div>
<div class="paragraph">
<p>The blue and green dotted arrows in the diagram below illustrate the additional sequences that are allowed when a command has repeatable subcommands.</p>
</div>
<div id="sequences-when-subcommands-repeatable" class="imageblock">
<div class="content">
<img src="images/subcommands-repeatable.png" alt="subcommands repeatable">
</div>
<div class="title">Figure 2. If a command is marked to allow repeatable subcommands, the additional valid sequences of its subcommands form a fully connected subgraph.</div>
</div>
<div class="paragraph">
<p>Note that it is not valid to specify a subcommand followed by its parent command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash"># invalid: cannot move _up_ the hierarchy
myapp add -x=item1 -w=0.2 myapp</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_repeatable_subcommands_execution">16.10.3. Repeatable Subcommands Execution</h4>
<div class="paragraph">
<p>The default <a href="#_executing_commands_with_subcommands"><code>IExecutionStrategy</code></a> (<code>picocli.CommandLine.RunLast</code>) only executes the last subcommands <em>with the same parent</em>. For example, if</p>
</div>
<div class="listingblock">
<div class="content">
<pre>toplevelcmd subcmd-A subcmd-B subsub-B1 subsub-B2</pre>
</div>
</div>
<div class="paragraph">
<p>is invoked, only the last two sub-subcommands <code>subsub-B1</code> and <code>subsub-B2</code> (who both have parent command <code>subcmd-B</code>) are executed by default. You can <a href="https://picocli.info/apidocs/picocli/CommandLine.html#setExecutionStrategy-picocli.CommandLine.IExecutionStrategy-">set</a> a different <a href="https://picocli.info/apidocs/picocli/CommandLine.IExecutionStrategy.html">execution strategy</a> if this does not meet your needs.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_usage_help_for_subcommands">16.11. Usage Help for Subcommands</h3>
<div class="paragraph">
<p>After registering subcommands, calling the <code>commandLine.usage</code> method will show a usage help message that includes all registered subcommands. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">CommandLine commandLine = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> Git());

<span class="comment">// add subcommands programmatically (not necessary if the parent command</span>
<span class="comment">// declaratively registers the subcommands via annotation)</span>
commandLine.addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">status</span><span class="delimiter">&quot;</span></span>,   <span class="keyword">new</span> GitStatus());
commandLine.addSubcommand(<span class="string"><span class="delimiter">&quot;</span><span class="content">commit</span><span class="delimiter">&quot;</span></span>,   <span class="keyword">new</span> GitCommit());
...
commandLine.usage(<span class="predefined-type">System</span>.out);</code></pre>
</div>
</div>
<div class="paragraph">
<p>The usage help message shows the commands in the order they were registered:</p>
</div>
<div id="subcommand-help" class="listingblock">
<div class="content">
<pre>Usage: git [-hV] [--git-dir=&lt;gitDir&gt;] [COMMAND]
Git is a fast, scalable, distributed revision control system with an unusually
rich command set that provides both high-level operations and full access to
internals.
      --git-dir=&lt;gitDir&gt;   Set the path to the repository.
  -h, --help               Show this help message and exit.
  -V, --version            Print version information and exit.

Commands:

The most commonly used git commands are:
  help      Displays help information about the specified command
  status    Show the working tree status.
  commit    Record changes to the repository.
  add       Add file contents to the index.
  branch    List, create, or delete branches.
  checkout  Checkout a branch or paths to the working tree.
  clone     Clone a repository into a new directory.
  diff      Show changes between commits, commit and working tree, etc.
  merge     Join two or more development histories together.
  push      Update remote refs along with associated objects.
  rebase    Forward-port local commits to the updated upstream head.
  tag       Create, list, delete or verify a tag object signed with GPG.</pre>
</div>
</div>
<div class="paragraph">
<p>The description of each subcommand in the command list is taken from the subcommand&#8217;s first <code>header</code> line, or the first <code>description</code> line if it does not have a <code>header</code> defined.</p>
</div>
<div class="paragraph">
<p>The above usage help message is produced from the annotations on the class below:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">git</span><span class="delimiter">&quot;</span></span>, mixinStandardHelpOptions = <span class="predefined-constant">true</span>,
        version = <span class="string"><span class="delimiter">&quot;</span><span class="content">subcommand demo - picocli 3.0</span><span class="delimiter">&quot;</span></span>,
        subcommands = HelpCommand.class,
        description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Git is a fast, scalable, distributed revision control </span><span class="delimiter">&quot;</span></span> +
                      <span class="string"><span class="delimiter">&quot;</span><span class="content">system with an unusually rich command set that provides both </span><span class="delimiter">&quot;</span></span> +
                      <span class="string"><span class="delimiter">&quot;</span><span class="content">high-level operations and full access to internals.</span><span class="delimiter">&quot;</span></span>,
        commandListHeading = <span class="string"><span class="delimiter">&quot;</span><span class="content">%nCommands:%n%nThe most commonly used git commands are:%n</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">Git</span> {

  <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">--git-dir</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Set the path to the repository.</span><span class="delimiter">&quot;</span></span>)
  <span class="directive">private</span> <span class="predefined-type">File</span> gitDir;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above example uses the <a href="#_mixin_standard_help_options">mixinStandardHelpOptions</a> attribute to mix in
<a href="#_help_options"><code>usageHelp</code></a> and <a href="#_help_options"><code>versionHelp</code></a> options and registers the <code>help</code> subcommand.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Use the <code>@Spec</code> annotation for subcommands that need to show the usage help message explicitly.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>From picocli 3.1, the usage help synopsis of the subcommand shows not only the subcommand name but also the parent command name.
For example, if the <code>git</code> command has a <code>commit</code> subcommand, the usage help for the <code>commit</code> subcommand shows <code>Usage: git commit &lt;options&gt;</code>.</p>
</div>
<div class="paragraph">
<p>If a subcommand explicitly wants to show the usage help message, the <code>@Spec</code> annotation may be useful.
The injected <code>CommandSpec</code> has its parent command initialized correctly, so the usage help can show the fully qualified name of the subcommand.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">commit</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">...</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">Commit</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span> {
    <span class="annotation">@Spec</span> CommandSpec spec;

    <span class="directive">public</span> <span class="type">void</span> run() {
        <span class="keyword">if</span> (shouldShowHelp()) {
            spec.commandLine().usage(<span class="predefined-type">System</span>.out);
        }
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>For example, see <a href="#_section_headings">Section Headings</a> for an example subcommand (<code>git commit</code>), which produces the help message shown
in <a href="#_expanded_example">Expanded Example</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_hidden_subcommands">16.12. Hidden Subcommands</h3>
<div class="paragraph">
<p>Commands with the <code>hidden</code> attribute set to <code>true</code> will not be shown in the usage help message of their parent command.</p>
</div>
<div class="paragraph">
<p>For example, the <code>bar</code> subcommand below is annotated as <code>hidden = true</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">foo</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">This is a visible subcommand</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">Foo</span> { }

<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">bar</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">This is a hidden subcommand</span><span class="delimiter">&quot;</span></span>, hidden = <span class="predefined-constant">true</span>)
<span class="type">class</span> <span class="class">Bar</span> { }

<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">app</span><span class="delimiter">&quot;</span></span>, subcommands = {Foo.class, Bar.class})
<span class="type">class</span> <span class="class">App</span> { }</code></pre>
</div>
</div>
<div class="paragraph">
<p>The usage help message for <code>App</code> looks like the below. Note that the <code>bar</code> subcommand is not shown:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: app
Commands:
  foo  This is a visible subcommand</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_help_subcommands">16.13. Help Subcommands</h3>
<div class="paragraph">
<p>Commands with the <code>helpCommand</code> attribute set to <code>true</code> are treated as help commands.
When picocli encounters a help command on the command line, required options and required positional parameters of the parent command
are not validated (similar to <a href="#_help_options">help options</a>).</p>
</div>
<div class="paragraph">
<p>See <a href="#_custom_help_subcommands">Custom Help Subcommands</a> for more details on creating help subcommands.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(helpCommand = <span class="predefined-constant">true</span>)</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_required_subcommands">16.14. Required Subcommands</h3>
<div class="paragraph">
<p>For some command suites, it does not make sense to invoke the top-level command by itself, and the user is required to specify a subcommand.</p>
</div>
<div class="paragraph">
<p>Picocli does not offer direct support for making a subcommand required, but it does provide the tools to:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>display a synopsis that indicates that subcommands are mandatory</p>
</li>
<li>
<p>respond appropriately when the user input is invalid</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>By default, the synopsis of a command with subcommands shows <code>[COMMAND]</code>, indicating that a subcommand can optionally be specified.
To show that the subcommand is mandatory, set the <code>synopsisSubcommandLabel</code> attribute to <code>COMMAND</code>, without the <code>[</code> and <code>]</code> brackets.</p>
</div>
<div class="paragraph">
<p>If the end user invokes the top-level command without specifying a subcommand, one way to respond is to show an error message followed by the usage help of the top-level command.
This can be accomplished by letting the top-level command throw a <code>ParameterException</code>. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">git</span><span class="delimiter">&quot;</span></span>, synopsisSubcommandLabel = <span class="string"><span class="delimiter">&quot;</span><span class="content">COMMAND</span><span class="delimiter">&quot;</span></span>, subcommands = { ... })
<span class="type">class</span> <span class="class">Git</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span> {
    <span class="annotation">@Spec</span> CommandSpec spec;
    <span class="directive">public</span> <span class="type">void</span> run() {
        <span class="keyword">throw</span> <span class="keyword">new</span> ParameterException(spec.commandLine(), <span class="string"><span class="delimiter">&quot;</span><span class="content">Missing required subcommand</span><span class="delimiter">&quot;</span></span>);
    }
    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span>... args) {
        <span class="predefined-type">System</span>.exit(<span class="keyword">new</span> CommandLine(<span class="keyword">new</span> Git()).execute(args));
    }
}</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_reuse">17. Reuse</h2>
<div class="sectionbody">
<div class="paragraph">
<p>You may find yourself defining the same options, parameters or command attributes in many command line applications.
To reduce duplication, picocli supports both subclassing and mixins as ways to reuse such options and attributes.</p>
</div>
<div class="paragraph">
<p>For both mechanisms, the first step is to extract these options, parameters and command attributes into a separate class. Below is an example class, <code>ReusableOptions</code>, that we will use in example scenarios in this chapter:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(synopsisHeading      = <span class="string"><span class="delimiter">&quot;</span><span class="content">%nUsage:%n%n</span><span class="delimiter">&quot;</span></span>,
         descriptionHeading   = <span class="string"><span class="delimiter">&quot;</span><span class="content">%nDescription:%n%n</span><span class="delimiter">&quot;</span></span>,
         parameterListHeading = <span class="string"><span class="delimiter">&quot;</span><span class="content">%nParameters:%n%n</span><span class="delimiter">&quot;</span></span>,
         optionListHeading    = <span class="string"><span class="delimiter">&quot;</span><span class="content">%nOptions:%n%n</span><span class="delimiter">&quot;</span></span>,
         commandListHeading   = <span class="string"><span class="delimiter">&quot;</span><span class="content">%nCommands:%n%n</span><span class="delimiter">&quot;</span></span>)
<span class="directive">public</span> <span class="type">class</span> <span class="class">ReusableOptions</span> {

    <span class="annotation">@Option</span>(names = { <span class="string"><span class="delimiter">&quot;</span><span class="content">-v</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--verbose</span><span class="delimiter">&quot;</span></span> }, description = {
        <span class="string"><span class="delimiter">&quot;</span><span class="content">Specify multiple -v options to increase verbosity.</span><span class="delimiter">&quot;</span></span>,
        <span class="string"><span class="delimiter">&quot;</span><span class="content">For example, `-v -v -v` or `-vvv`</span><span class="delimiter">&quot;</span></span> })
    <span class="directive">protected</span> <span class="type">boolean</span><span class="type">[]</span> verbosity = <span class="keyword">new</span> <span class="type">boolean</span>[<span class="integer">0</span>];
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This defines some usage help attributes that give a spacious layout, and a <code>verbosity</code> option that makes the operation more talkative.</p>
</div>
<div class="sect2">
<h3 id="_subclassing">17.1. Subclassing</h3>
<div class="paragraph">
<p>One way to reuse the above option and attributes is to extend the class. Picocli will walk the class hierarchy to check for annotations, so <code>@Options</code>, <code>@Parameters</code> and <code>@Command</code> attributes declared on a superclass are available in all subclasses.</p>
</div>
<div class="paragraph">
<p>For example, all commands that extend the <a href="#_reuse">above sample</a> <code>ReusableOptions</code> class will inherit the <code>--verbose</code> option, and generate a usage help message in the same spacious style. Example code:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">zip</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Example reuse by subclassing</span><span class="delimiter">&quot;</span></span>)
<span class="directive">public</span> <span class="type">class</span> <span class="class">MyCommand</span> <span class="directive">extends</span> ReusableOptions { ... }</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_mixins">17.2. Mixins</h3>
<div class="paragraph">
<p>Picocli 3.0 introduces the concept of "mixins". Mixins are a convenient alternative to subclassing:
picocli annotations from <em>any</em> class can be added to ("mixed in" with) another command.
This includes options, positional parameters, subcommands and command attributes.
Picocli <a href="#_mixin_standard_help_options">mixinStandardHelpOptions</a> internally uses a mixin.</p>
</div>
<div class="paragraph">
<p>A mixin is a separate class with options, positional parameters, subcommands and command attributes
that you want to reuse in other commands.
Mixins can be installed by calling the <code>CommandLine.addMixin</code> method with an object of this class, or annotating a field in your command with <code>@Mixin</code>.</p>
</div>
<div class="sect3">
<h4 id="_adding_mixins_programmatically">17.2.1. Adding Mixins Programmatically</h4>
<div class="paragraph">
<p>The below example shows how a mixin can be added programmatically with the <code>CommandLine.addMixin</code> method.
We use the sample <code>ReusableOptions</code> class <a href="#_reuse">defined above</a> as the mixin:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">CommandLine commandLine = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MyCommand());

ReusableOptions mixin = <span class="keyword">new</span> ReusableOptions();
commandline.addMixin(<span class="string"><span class="delimiter">&quot;</span><span class="content">myMixin</span><span class="delimiter">&quot;</span></span>, mixin);</code></pre>
</div>
</div>
<div class="paragraph">
<p>Programmatically added mixins can be accessed via the map returned by <code>CommandLine.getMixins</code>. Continuing from the previous example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">commandLine.parseArgs(<span class="string"><span class="delimiter">&quot;</span><span class="content">-vvv</span><span class="delimiter">&quot;</span></span>);

<span class="comment">// the options defined in ReusableOptions have been added to the zip command</span>
<span class="keyword">assert</span> mixin == commandLine.getMixins().get(<span class="string"><span class="delimiter">&quot;</span><span class="content">myMixin</span><span class="delimiter">&quot;</span></span>);
<span class="keyword">assert</span> mixin.verbosity.length == <span class="integer">3</span>;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_mixin_annotation">17.2.2. <code>@Mixin</code> Annotation</h4>
<div class="paragraph">
<p>A command can also include a mixin by annotating a field with <code>@Mixin</code>. All picocli annotations found in the mixin class
are added to the command that has a field annotated with <code>@Mixin</code>. For example, again using the sample <code>ReusableOptions</code> class <a href="#_reuse">defined above</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">zip</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Example reuse with @Mixin annotation.</span><span class="delimiter">&quot;</span></span>)
<span class="directive">public</span> <span class="type">class</span> <span class="class">MyCommand</span> {

    <span class="comment">// adds the options defined in ReusableOptions to this command</span>
    <span class="annotation">@Mixin</span>
    <span class="directive">private</span> ReusableOptions myMixin;
    ...
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>In addition to adding the options, subcommands and command attributes of the mixed-in object to the command,
the mixed-in object is also injected into the field annotated with <code>@Mixin</code>, making it trivial for the command to reference the mixed-in object if necessary.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">MyCommand zip = <span class="keyword">new</span> MyCommand();
CommandLine commandLine = <span class="keyword">new</span> CommandLine(zip);
commandLine.parseArgs(<span class="string"><span class="delimiter">&quot;</span><span class="content">-vvv</span><span class="delimiter">&quot;</span></span>);

<span class="comment">// the options defined in ReusableOptions have been added to the zip command</span>
<span class="keyword">assert</span> zip.myMixin.verbosity.length == <span class="integer">3</span>;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Mixins added with the <code>@Mixin</code> annotation can also be accessed via the map returned by <code>CommandLine.getMixins</code>.</p>
</div>
<div class="paragraph">
<p>The GitHub project has a <a href="https://github.com/remkop/picocli/tree/master/picocli-examples/src/main/java/picocli/examples/mixin">full working example</a>.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_use_case_sharing_options">17.3. Use Case: Sharing Options</h3>
<div class="paragraph">
<p>A common use case is sharing options between different levels of the command hierarchy, so that "global" options from the top-level command are also available on subcommands.</p>
</div>
<div class="paragraph">
<p>Since picocli 4.2, <a href="#_parentcommand_annotation"><code>@ParentCommand</code>-annotated</a> fields can be used in mixins, which makes this easier. Here is an example implementation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="comment">// Define a mixin that delegates to the parent command.</span>
<span class="type">class</span> <span class="class">MyMixin</span> {
    <span class="annotation">@ParentCommand</span> Top top;

    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-v</span><span class="delimiter">&quot;</span></span>)
    <span class="directive">public</span> <span class="type">void</span> setVerbose(<span class="type">boolean</span><span class="type">[]</span> verbosity) { top.setVerbose(verbosity); }
}

<span class="comment">// An example Top-level command with two subcommands.</span>
<span class="comment">// The `-v` option can be specified on the top-level command as well as the subcommands.</span>
<span class="annotation">@Command</span>(subcommands = Sub2.class)
<span class="type">class</span> <span class="class">Top</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span> {
    <span class="directive">private</span> <span class="type">boolean</span><span class="type">[]</span> verbosity = <span class="keyword">new</span> <span class="type">boolean</span>[<span class="integer">0</span>];

    <span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-v</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--verbose</span><span class="delimiter">&quot;</span></span>})
    <span class="directive">public</span> <span class="type">void</span> setVerbose(<span class="type">boolean</span><span class="type">[]</span> verbosity) { <span class="local-variable">this</span>.verbosity = verbosity; }

    <span class="directive">public</span> <span class="type">void</span> verbose(<span class="predefined-type">String</span> pattern, <span class="predefined-type">Object</span>... params) {
        <span class="keyword">if</span> (verbosity.length &gt;= <span class="integer">1</span>) {
            <span class="predefined-type">System</span>.out.printf(pattern, params);
        }
    }

    <span class="directive">public</span> <span class="type">void</span> run() { verbose(<span class="string"><span class="delimiter">&quot;</span><span class="content">Hello from top%n</span><span class="delimiter">&quot;</span></span>); }

    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) {
        <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> Top()).execute(args);
    }

    <span class="comment">// The @Mixin-annotated parameter adds the `-v` option to this subcommand.</span>
    <span class="annotation">@Command</span>
    <span class="type">void</span> sub1(<span class="annotation">@Mixin</span> MyMixin mymixin) { verbose(<span class="string"><span class="delimiter">&quot;</span><span class="content">Hello from sub1%n</span><span class="delimiter">&quot;</span></span>); }
}

<span class="comment">// Subcommand classes can mix in the `-v` option with a @Mixin-annotated field.</span>
<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">sub2</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">Sub2</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span>{
    <span class="annotation">@Mixin</span> MyMixin mymixin;

    <span class="annotation">@Override</span>
    <span class="directive">public</span> <span class="type">void</span> run() { mymixin.top.verbose(<span class="string"><span class="delimiter">&quot;</span><span class="content">Hello from sub2%n</span><span class="delimiter">&quot;</span></span>); }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>With this, the <code>-v</code> option can be specified on the top-level command as well as the subcommands, so all of the below are valid invocations:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>java Top -v
java Top -v sub1
java Top sub1 -v
java Top -v sub2
java Top sub2 -v</pre>
</div>
</div>
<div class="paragraph">
<p>All of these invocations will print some output, since the <code>-v</code> option was specified.</p>
</div>
<div class="paragraph">
<p>For mixins that need to be reusable across more than two levels in the command hierarchy, injecting a <a href="#_spec_annotation"><code>@Spec</code>-annotated</a> field gives the mixin access to the full command hierarchy.</p>
</div>
</div>
<div class="sect2">
<h3 id="_reuse_combinations">17.4. Reuse Combinations</h3>
<div class="paragraph">
<p>The above mechanisms can be combined in any way. Mixins can be nested, and there is no limitation to how deeply mixins can be nested. A mixin may also inherit options, positional parameters and command attributes from a super class.</p>
</div>
<div class="paragraph">
<p>An option with the same name should not be defined multiple times or a <code>DuplicateOptionAnnotationsException</code> is thrown during initialization. Positional parameters for the same position may be defined multiple times, they can co-exist.</p>
</div>
<div class="paragraph">
<p>Command attributes may be defined multiple times, but only one value is preserved. In case a command attribute is defined multiple times, the definition earlier in the following list takes priority over later in the list:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>@Command attributes of the command itself</p>
</li>
<li>
<p>Attributes on the @Mixin commands</p>
</li>
<li>
<p>Attributes on a @Mixin nested in a @Mixin of the command</p>
</li>
<li>
<p>Attributes on superclass of nested @Mixin</p>
</li>
<li>
<p>Attributes on superclass of @Mixin</p>
</li>
<li>
<p>Attributes on superclass of the command</p>
</li>
<li>
<p>Attributes on programmatically added mixins</p>
</li>
</ol>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_internationalization">18. Internationalization</h2>
<div class="sectionbody">
<div class="paragraph">
<p>As of version 3.6, usage help message sections and the description for options and positional parameters can be specified in a resource bundle.
A resource bundle can be set via annotations and programmatically.</p>
</div>
<div class="paragraph">
<p>In order to get you started quickly, the <a href="https://github.com/remkop/picocli/blob/master/picocli-examples"><code>picocli-examples</code></a> module has a minimal i18n example, coded both in <a href="https://github.com/remkop/picocli/blob/master/picocli-examples/src/main/java/picocli/examples/i18n/I18NDemo.java">Java</a> and <a href="https://github.com/remkop/picocli/tree/master/picocli-examples/src/main/kotlin/picocli/examples/kotlin/i18n/I18NDemo.kt">Kotlin</a>.</p>
</div>
<div class="sect2">
<h3 id="_configuration">18.1. Configuration</h3>
<div class="paragraph">
<p>Annotation example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">i18n-demo</span><span class="delimiter">&quot;</span></span>, resourceBundle = <span class="string"><span class="delimiter">&quot;</span><span class="content">my.org.I18nDemo_Messages</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">I18nDemo</span> {}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Programmatic example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span> <span class="type">class</span> <span class="class">I18nDemo2</span> {}

CommandLine cmd = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> I18nDemo2());
cmd.setResourceBundle(<span class="predefined-type">ResourceBundle</span>.getBundle(<span class="string"><span class="delimiter">&quot;</span><span class="content">my.org.I18nDemo2_Messages</span><span class="delimiter">&quot;</span></span>));</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_example_resource_bundle">18.2. Example Resource Bundle</h3>
<div class="paragraph">
<p>Example properties resource bundle:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code># Usage Help Message Sections
# ---------------------------
# Numbered resource keys can be used to create multi-line sections.
usage.headerHeading = This is my app. It does stuff. Good stuff.%n
usage.header   = header first line
usage.header.0 = header second line
usage.descriptionHeading = Description:%n
usage.description.0 = first line
usage.description.1 = second line
usage.description.2 = third line
usage.synopsisHeading = Usage:\u0020

# Leading whitespace is removed by default.
# Start with \u0020 to keep the leading whitespace.
usage.customSynopsis.0 =      Usage: ln [OPTION]... [-T] TARGET LINK_NAME   (1st form)
usage.customSynopsis.1 = \u0020 or:  ln [OPTION]... TARGET                  (2nd form)
usage.customSynopsis.2 = \u0020 or:  ln [OPTION]... TARGET... DIRECTORY     (3rd form)

# Headings can contain the %n character to create multi-line values.
usage.parameterListHeading = %nPositional parameters:%n
usage.optionListHeading = %nOptions:%n
usage.commandListHeading = %nCommands:%n
usage.footerHeading = Powered by picocli%n
usage.footer = footer

# Option Descriptions
# -------------------
# Use numbered keys to create multi-line descriptions.

# Example description for an option `@Option(names = "-x")`
x = This is the description for the -x option

# Example multi-line description for an option `@Option(names = "-y")`
y.0 = This is the first line of the description for the -y option
y.1 = This is the second line of the description for the -y option

# Example descriptions for the standard help mixin options:
help = Show this help message and exit.
version = Print version information and exit.

# Exit Code Description
usage.exitCodeListHeading = Exit Codes:%n
usage.exitCodeList.0 = \u00200:Successful program execution. (notice leading space '\u0020')
usage.exitCodeList.1 = 64:Usage error: user input for the command was incorrect.
usage.exitCodeList.2 = 70:An exception occurred when invoking the business logic of this command.</code></pre>
</div>
</div>
<div class="paragraph">
<p>For options and positional parameters, the optional annotation attribute <code>descriptionKey</code> can be used to localize the description. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>, descriptionKey = <span class="string"><span class="delimiter">&quot;</span><span class="content">xoption</span><span class="delimiter">&quot;</span></span>) <span class="type">int</span> x;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The matching entry in the resource bundle could look like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>xoption = This is the description for the -x option.</code></pre>
</div>
</div>
<div class="paragraph">
<p>When the <code>descriptionKey</code> is omitted, the <a href="https://picocli.info/apidocs/picocli/CommandLine.Option.html#descriptionKey--">fallback for options</a> is any option name without the leading dashes, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-v</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--verbose</span><span class="delimiter">&quot;</span></span>}) <span class="type">boolean</span><span class="type">[]</span> verbose;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The matching entry in the resource bundle could look like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>verbose = Show more detail during execution. \
          May be specified multiple times for increasing verbosity.</pre>
</div>
</div>
<div class="paragraph">
<p>For <a href="https://picocli.info/apidocs/picocli/CommandLine.Parameters.html#descriptionKey--">positional parameters</a> the fallback key is the <code>paramLabel + [ index ]</code>, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Parameters</span>(index = <span class="string"><span class="delimiter">&quot;</span><span class="content">0..*</span><span class="delimiter">&quot;</span></span>, paramLabel=<span class="string"><span class="delimiter">&quot;</span><span class="content">FILES</span><span class="delimiter">&quot;</span></span>) <span class="predefined-type">File</span><span class="type">[]</span>;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The matching entry in the resource bundle could look like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>FILES[0..*] = The files to process.</pre>
</div>
</div>
<div class="paragraph">
<p>For argument groups, use the <code>headingKey</code> to specify a resource bundle key. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@ArgGroup</span>(headingKey = <span class="string"><span class="delimiter">&quot;</span><span class="content">myBundleKey</span><span class="delimiter">&quot;</span></span>) MyArgGroup myGroup;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The matching entry in the resource bundle could look like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>myBundleKey = The localized heading for this argument group%n</pre>
</div>
</div>
<div class="paragraph">
<p>Note that the heading text should end with <code>%n</code> or the first option in the group will be on the same line.
This is to be consistent with other <a href="#_section_headings">section headings</a> in the usage help.</p>
</div>
</div>
<div class="sect2">
<h3 id="_shared_resource_bundles">18.3. Shared Resource Bundles</h3>
<div class="paragraph">
<p>Resources for multiple commands can be specified in a single ResourceBundle. Keys and their value can be
shared by multiple commands (so you don&#8217;t need to repeat them for every command), but alternatively, keys can be prefixed with
<code>command name + "."</code> to specify different values for different commands.
The most specific key wins. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>jfrog.rt.usage.header = Artifactory commands
jfrog.rt.config.usage.header = Configure Artifactory details.
jfrog.rt.upload.usage.header = Upload files.

# shared between all commands
usage.footerHeading = Environment Variables:
usage.footer.0 = footer line 0
usage.footer.1 = footer line 1</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_localizing_the_built_in_help">18.4. Localizing the Built-In Help</h3>
<div class="paragraph">
<p>The built-in <code>picocli.CommandLine.HelpCommand</code> can be localized as follows:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>help.usage.header</code> controls the help command summary in the subcommand list</p>
</li>
<li>
<p><code>helpCommand.help</code> is the resource bundle key for the <code>--help</code> option of the help subcommand</p>
</li>
<li>
<p><code>helpCommand.command</code> is the resource bundle key for the <code>COMMAND</code> positional parameter of the help subcommand</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code># for a specific subcommand, e.g., `parent help`
parent.help.usage.header=This is the `help` subcommand of the `parent` command
parent.help.helpCommand.help = Specialized description of --help option of help subcommand for parent command
parent.help.helpCommand.command = Specialized description of COMMAND parameter of help subcommand for parent command

# or have one global entry for the `help` subcommand (for any and all commands)
help.usage.header=This is the `help` subcommand
helpCommand.help = Shared description of --help option of built-in help subcommand
helpCommand.command = Shared description of COMMAND parameter of built-in help subcommand</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_localizing_default_values">18.5. Localizing Default Values</h3>
<div class="paragraph">
<p>Options with a <a href="#_default_values">default value</a> can use the <code>${DEFAULT-VALUE}</code> variable in the localized option description in the resource bundle:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>userName=Specify the user name. The default is ${DEFAULT-VALUE}.</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_variable_interpolation">19. Variable Interpolation</h2>
<div class="sectionbody">
<div class="paragraph">
<p>From 4.0, picocli supports variable interpolation (variable expansion) in annotation attributes as well as in text attributes of the programmatic API.</p>
</div>
<div class="sect2">
<h3 id="_variable_interpolation_example">19.1. Variable Interpolation Example</h3>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">status</span><span class="delimiter">&quot;</span></span>,
         description = <span class="string"><span class="delimiter">&quot;</span><span class="content">This command logs the ${COMMAND-NAME} for ${PARENT-COMMAND-NAME}.</span><span class="delimiter">&quot;</span></span>,
         version = {
            <span class="string"><span class="delimiter">&quot;</span><span class="content">Versioned Command 1.0</span><span class="delimiter">&quot;</span></span>,
            <span class="string"><span class="delimiter">&quot;</span><span class="content">Picocli </span><span class="delimiter">&quot;</span></span> + picocli.CommandLine.VERSION,
            <span class="string"><span class="delimiter">&quot;</span><span class="content">JVM: ${java.version} (${java.vendor} ${java.vm.name} ${java.vm.version})</span><span class="delimiter">&quot;</span></span>,
            <span class="string"><span class="delimiter">&quot;</span><span class="content">OS: ${os.name} ${os.version} ${os.arch}</span><span class="delimiter">&quot;</span></span>})
<span class="type">class</span> <span class="class">Status</span> {
    <span class="comment">// -d or --directories</span>
    <span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">${dirOptionName1:--d}</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">${dirOptionName2:---directories}</span><span class="delimiter">&quot;</span></span>},
            description = {<span class="string"><span class="delimiter">&quot;</span><span class="content">Specify one or more directories, </span><span class="delimiter">&quot;</span></span> +
                               <span class="string"><span class="delimiter">&quot;</span><span class="content">separated by '${sys:path.separator}'.</span><span class="delimiter">&quot;</span></span>,
                           <span class="string"><span class="delimiter">&quot;</span><span class="content">The default is the user home directory (${DEFAULT-VALUE}).</span><span class="delimiter">&quot;</span></span>},
            arity = <span class="string"><span class="delimiter">&quot;</span><span class="content">${sys:dirOptionArity:-1..*}</span><span class="delimiter">&quot;</span></span>,
            defaultValue = <span class="string"><span class="delimiter">&quot;</span><span class="content">${sys:user.home}</span><span class="delimiter">&quot;</span></span>,
            split = <span class="string"><span class="delimiter">&quot;</span><span class="content">${sys:path.separator}</span><span class="delimiter">&quot;</span></span>)
    <span class="predefined-type">String</span><span class="type">[]</span> directories;
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_predefined_variables">19.2. Predefined Variables</h3>
<div class="paragraph">
<p>The following variables are predefined:</p>
</div>
<table class="tableblock frame-all grid-cols stretch">
<colgroup>
<col style="width: 30%;">
<col style="width: 10%;">
<col style="width: 30%;">
<col style="width: 30%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Variable</th>
<th class="tableblock halign-left valign-middle">Since</th>
<th class="tableblock halign-left valign-top">Use in</th>
<th class="tableblock halign-left valign-top">Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>${DEFAULT-VALUE}</code></p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">3.2</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">the description for an option or positional parameter</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">replaced with the <a href="#defaultValue-annotation">default value</a> for that option or positional parameter</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>${FALLBACK-VALUE}</code></p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">4.0</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">the description for an option with optional parameter</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">replaced with the <a href="#fallbackValue-annotation">fallback value</a> for that option or positional parameter</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>${COMPLETION-CANDIDATES}</code></p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">3.2</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">the description for an option or positional parameter</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">replaced with the completion candidates for that option or positional parameter</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>${COMMAND-NAME}</code></p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">4.0</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">any section of the usage help message for a command</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">replaced with the name of the command</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>${COMMAND-FULL-NAME}</code></p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">4.0</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">any section of the usage help message for a command</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">replaced with the fully qualified name of the command (that is, preceded by its parent fully qualified name)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>${PARENT-COMMAND-NAME}</code></p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">4.0</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">any section of the usage help message for a command</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">replaced with the name of its parent command</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>${PARENT-COMMAND-FULL-NAME}</code></p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">4.0</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">any section of the usage help message for a command</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">replaced with the fully qualified name of its parent command (that is, preceded by the name(s) of the parent command&#8217;s ancestor commands)</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="_custom_variables">19.3. Custom Variables</h3>
<div class="paragraph">
<p>In addition, you can define your own variables. Currently the following syntaxes are supported:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>${sys:key}</code>: system property lookup, replaced by the value of <code>System.getProperty("key")</code></p>
</li>
<li>
<p><code>${env:key}</code>: environment variable lookup, replaced by the value of <code>System.getEnv("key")</code></p>
</li>
<li>
<p><code>${bundle:key}</code>: look up the value of <code>key</code> in the resource bundle of the command</p>
</li>
<li>
<p><code>${key}</code>: search all of the above, first system properties, then environment variables, and finally the resource bundle of the command</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="_default_values_for_custom_variables">19.4. Default Values for Custom Variables</h3>
<div class="paragraph">
<p>You can specify a default value to use when no value is found for a custom variable. The syntax for specifying a default is <code>${a:-b}</code>, where <code>a</code> is the variable name and <code>b</code> is the default value to use if <code>a</code> is not found.</p>
</div>
<div class="paragraph">
<p>So, for the individual lookups, this looks like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>${key:-defaultValue}
${sys:key:-defaultValue}
${env:key:-defaultValue}
${bundle:key:-defaultValue}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The default value may contain other custom variables. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>${bundle:a:-${env:b:-${sys:c:-X}}}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above variable is expanded as follows. First, try to find key <code>a</code> in the command&#8217;s resource bundle. If <code>a</code> is not found in the resource bundle, get the value of environment variable <code>b</code>. If no environment variable <code>b</code> exists, get the value of system property <code>c</code>. Finally, no system property <code>c</code> exists, the value of the expression becomes <code>X</code>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_escaping_variables">19.5. Escaping Variables</h3>
<div class="paragraph">
<p>Sometimes you want to show a string like <code>"${VAR}"</code> in a description.
A <code>$</code> character can be escaped with another <code>$</code> character. Therefore, <code>$${VAR}</code> will not be interpreted as a <code>VAR</code> variable, but will be replaced by <code>${VAR}</code> instead.</p>
</div>
</div>
<div class="sect2">
<h3 id="_switching_off_variable_interpolation">19.6. Switching Off Variable Interpolation</h3>
<div class="paragraph">
<p>Variable interpolation can be switched off for the full command hierarchy by calling <code>CommandLine.setInterpolateVariables(false)</code>, or for a particular command by calling <code>CommandSpec.interpolateVariables(false)</code>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_limitations_of_variable_interpolation">19.7. Limitations of Variable Interpolation</h3>
<div class="paragraph">
<p>Some attribute values need to be resolved early, when the model is constructed from the annotation values.</p>
</div>
<div class="paragraph">
<p>Specifically:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>command names and aliases, option names, mixin names</p>
</li>
<li>
<p><code>arity</code> (for options and positional parameters)</p>
</li>
<li>
<p><code>index</code> (for positional parameters)</p>
</li>
<li>
<p><code>separator</code> (for commands)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>It is possible for these attributes to contain variables, but be aware of the limitations.</p>
</div>
<div class="paragraph">
<p>If these attributes have variables, and the variables get a different value after the model is constructed, the change will not be reflected in the model.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_tips_tricks">20. Tips &amp; Tricks</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="option-parameters-methods">20.1. <code>@Option</code> and <code>@Parameters</code> Methods</h3>
<div class="paragraph">
<p>From version 3.2, <code>@Option</code> and <code>@Parameters</code> annotations can be added to methods as well as fields of a class.</p>
</div>
<div class="paragraph">
<p>For concrete classes, annotate "setter" methods (methods that accept a parameter) and when the option is specified on the command line, picocli will invoke the method with the value specified on the command line, converted to the type of the method parameter.</p>
</div>
<div class="paragraph">
<p>Alternatively, you may annotate "getter-like" methods (methods that return a value) on an interface, and picocli will create an instance of the interface that returns the values specified on the command line, converted to the method return type.</p>
</div>
<div class="sect3">
<h4 id="_annotating_methods_of_an_interface">20.1.1. Annotating Methods of an Interface</h4>
<div class="paragraph">
<p>The <code>@Option</code> and <code>@Parameters</code> annotations can be used on methods of an interface that return a value. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">interface</span> <span class="class">Counter</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">--count</span><span class="delimiter">&quot;</span></span>)
    <span class="type">int</span> getCount();
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You use it by specifying the class of the interface:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">CommandLine cmd = <span class="keyword">new</span> CommandLine(Counter.class); <span class="comment">// specify a class</span>
<span class="predefined-type">String</span><span class="type">[]</span> args = <span class="keyword">new</span> <span class="predefined-type">String</span><span class="type">[]</span> {<span class="string"><span class="delimiter">&quot;</span><span class="content">--count</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">3</span><span class="delimiter">&quot;</span></span>};
cmd.parseArgs(args);
Counter counter = cmd.getCommand(); <span class="comment">// picocli created an instance</span>
<span class="keyword">assert</span> counter.getCount() == <span class="integer">3</span>; <span class="comment">// method returns command line value</span></code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_annotating_methods_of_a_concrete_class">20.1.2. Annotating Methods of a Concrete Class</h4>
<div class="paragraph">
<p>The <code>@Option</code> and <code>@Parameters</code> annotations can be used on methods of a class that accept a parameter. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">Counter</span> {
    <span class="type">int</span> count;

    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">--count</span><span class="delimiter">&quot;</span></span>)
    <span class="type">void</span> setCount(<span class="type">int</span> count) {
        <span class="local-variable">this</span>.count = count;
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>You use it by passing an instance of the class:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">Counter counter = <span class="keyword">new</span> Counter(); <span class="comment">// the instance to populate</span>
CommandLine cmd = <span class="keyword">new</span> CommandLine(counter);
<span class="predefined-type">String</span><span class="type">[]</span> args = <span class="keyword">new</span> <span class="predefined-type">String</span><span class="type">[]</span> {<span class="string"><span class="delimiter">&quot;</span><span class="content">--count</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">3</span><span class="delimiter">&quot;</span></span>};
cmd.parseArgs(args);
<span class="keyword">assert</span> counter.count == <span class="integer">3</span>; <span class="comment">// method was invoked with command line value</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Methods annotated with <code>@Option</code> and <code>@Parameters</code> can do simple input validation by throwing a <code>ParameterException</code> when invalid values are specified on the command line.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">ValidationExample</span> {
    <span class="directive">private</span> <span class="predefined-type">Map</span>&lt;<span class="predefined-type">String</span>, <span class="predefined-type">String</span>&gt; properties = <span class="keyword">new</span> <span class="predefined-type">LinkedHashMap</span>&lt;&gt;();

    <span class="annotation">@Spec</span> <span class="directive">private</span> CommandSpec spec; <span class="comment">// injected by picocli</span>

    <span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-D</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--property</span><span class="delimiter">&quot;</span></span>}, paramLabel = <span class="string"><span class="delimiter">&quot;</span><span class="content">KEY=VALUE</span><span class="delimiter">&quot;</span></span>)
    <span class="directive">public</span> <span class="type">void</span> setProperty(<span class="predefined-type">Map</span>&lt;<span class="predefined-type">String</span>, <span class="predefined-type">String</span>&gt; map) {
        <span class="keyword">for</span> (<span class="predefined-type">String</span> key : map.keySet()) {
            <span class="predefined-type">String</span> newValue = map.get(key);
            validateUnique(key, newValue);
            properties.put(key, newValue);
        }
    }

    <span class="directive">private</span> <span class="type">void</span> validateUnique(<span class="predefined-type">String</span> key, <span class="predefined-type">String</span> newValue) {
        <span class="predefined-type">String</span> existing = properties.get(key);
        <span class="keyword">if</span> (existing != <span class="predefined-constant">null</span> &amp;&amp; !existing.equals(newValue)) {
            <span class="keyword">throw</span> <span class="keyword">new</span> ParameterException(spec.commandLine(),
                    <span class="predefined-type">String</span>.format(<span class="string"><span class="delimiter">&quot;</span><span class="content">Duplicate key '%s' for values '%s' and '%s'.</span><span class="delimiter">&quot;</span></span>,
                    key, existing, newValue));
        }
    }
    <span class="comment">// ...</span>
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="command-methods">20.2. <a id="_command-methods"></a> <code>@Command</code> Methods</h3>
<div class="paragraph">
<p>From picocli 3.6, methods can be annotated with <code>@Command</code>.
The method parameters provide the command options and parameters. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">Cat</span> {
    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) {
        <span class="predefined-type">Method</span> doit = CommandLine.getCommandMethods(Cat.class, <span class="string"><span class="delimiter">&quot;</span><span class="content">cat</span><span class="delimiter">&quot;</span></span>).get(<span class="integer">0</span>);
        CommandLine cmd = <span class="keyword">new</span> CommandLine(doit);
        <span class="type">int</span> exitCode = cmd.execute(args);
    }

    <span class="annotation">@Command</span>(description = <span class="string"><span class="delimiter">&quot;</span><span class="content">Concatenate FILE(s) to standard output.</span><span class="delimiter">&quot;</span></span>,
             mixinStandardHelpOptions = <span class="predefined-constant">true</span>, version = <span class="string"><span class="delimiter">&quot;</span><span class="content">4.1.3</span><span class="delimiter">&quot;</span></span>)
    <span class="type">void</span> cat(<span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-E</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--show-ends</span><span class="delimiter">&quot;</span></span>}) <span class="type">boolean</span> showEnds,
             <span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-n</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--number</span><span class="delimiter">&quot;</span></span>}) <span class="type">boolean</span> number,
             <span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-T</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--show-tabs</span><span class="delimiter">&quot;</span></span>}) <span class="type">boolean</span> showTabs,
             <span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-v</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--show-nonprinting</span><span class="delimiter">&quot;</span></span>}) <span class="type">boolean</span> showNonPrinting,
             <span class="annotation">@Parameters</span>(paramLabel = <span class="string"><span class="delimiter">&quot;</span><span class="content">FILE</span><span class="delimiter">&quot;</span></span>) <span class="predefined-type">File</span><span class="type">[]</span> files) {
        <span class="comment">// process files</span>
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The usage help of the above command looks like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: cat [-EhnTvV] [FILE...]
Concatenate FILE(s) to standard output.
      [FILE...]
  -E, --show-ends
  -h, --help               Show this help message and exit.
  -n, --number
  -T, --show-tabs
  -v, --show-nonprinting
  -V, --version            Print version information and exit.</pre>
</div>
</div>
<div class="paragraph">
<p>See below for an example that uses a <a href="#_internationalization">resource bundle</a> to define usage help descriptions outside the code.</p>
</div>
<div class="paragraph">
<p>For positional parameters, the <code>@Parameters</code> annotation may be omitted on method parameters.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
If compiled with the <code>-parameters</code> flag on Java 8 or higher, the <code>paramLabel</code> of positional parameters is obtained from the method parameter name using reflection instead of the generic arg0, arg1, etc.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="_subcommand_methods">20.2.1. Subcommand Methods</h4>
<div class="paragraph">
<p>If the enclosing class is annotated with <code>@Command</code>, method commands are automatically added as subcommands to the class command, unless the class command has attribute <code>@Command(addMethodSubcommands = false)</code>.
For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">git</span><span class="delimiter">&quot;</span></span>, mixinStandardHelpOptions = <span class="predefined-constant">true</span>, version = <span class="string"><span class="delimiter">&quot;</span><span class="content">picocli-4.1.3</span><span class="delimiter">&quot;</span></span>,
         resourceBundle = <span class="string"><span class="delimiter">&quot;</span><span class="content">Git_Messages</span><span class="delimiter">&quot;</span></span>, subcommands = { HelpCommand.class })
<span class="type">class</span> <span class="class">Git</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">--git-dir</span><span class="delimiter">&quot;</span></span>, descriptionKey = <span class="string"><span class="delimiter">&quot;</span><span class="content">GITDIR</span><span class="delimiter">&quot;</span></span>)
    Path path;

    <span class="annotation">@Command</span>
    <span class="type">void</span> commit(<span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-m</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--message</span><span class="delimiter">&quot;</span></span>}) <span class="predefined-type">String</span> commitMessage,
                <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">--squash</span><span class="delimiter">&quot;</span></span>, paramLabel = <span class="string"><span class="delimiter">&quot;</span><span class="content">&lt;commit&gt;</span><span class="delimiter">&quot;</span></span>) <span class="predefined-type">String</span> squash,
                <span class="annotation">@Parameters</span>(paramLabel = <span class="string"><span class="delimiter">&quot;</span><span class="content">&lt;file&gt;</span><span class="delimiter">&quot;</span></span>) <span class="predefined-type">File</span><span class="type">[]</span> files) {
        <span class="comment">// ... implement business logic</span>
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Use <code>@Command(addMethodSubcommands = false)</code> on the class <code>@Command</code> annotation if the <code>@Command</code>-annotated methods in this class should not be added as subcommands.</p>
</div>
</div>
<div class="sect3">
<h4 id="_description_text_in_resourcebundle">20.2.2. Description Text in ResourceBundle</h4>
<div class="paragraph">
<p>The usage help of the above <code>git commit</code> example command is very minimal:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: git commit [--squash=&lt;commit&gt;] [-m=&lt;arg0&gt;] [&lt;file&gt;...]
      [&lt;file&gt;...]
      --squash=&lt;commit&gt;
  -m, --message=&lt;arg0&gt;</pre>
</div>
</div>
<div class="paragraph">
<p>You can use a <a href="#_internationalization">resource bundle</a> to move the descriptions out of the code:</p>
</div>
<div class="listingblock">
<div class="content">
<pre># shared between all commands
help = Show this help message and exit.
version = Print version information and exit.

# command-specific strings
git.usage.description = Version control system
git.GITDIR = Set the path to the repository

git.commit.usage.description = Record changes to the repository
git.commit.message = Use the given &lt;msg&gt; as the commit message.
git.commit.squash = Construct a commit message for use with rebase --autosquash.
git.commit.&lt;file&gt;[0..*] = The files to commit.</pre>
</div>
</div>
<div class="paragraph">
<p>With this resource bundle, the usage help for the <code>git commit</code> command looks like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Usage: git commit [--squash=&lt;commit&gt;] [-m=&lt;arg0&gt;] [&lt;file&gt;...]
Record changes to the repository
      [&lt;file&gt;...]         The files to commit.
      --squash=&lt;commit&gt;   Construct a commit message for use with rebase
                            --autosquash.
  -m, --message=&lt;arg0&gt;    Use the given &lt;msg&gt; as the commit message.</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_mixin_support_in_command_methods">20.2.3. Mixin Support in <code>@Command</code> Methods</h4>
<div class="paragraph">
<p>From picocli 3.8, <code>@Command</code> methods accept <code>@Mixin</code> parameters.
All options and positional parameters defined in the mixin class are added to the command.</p>
</div>
<div class="paragraph">
<p>Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">CommonParams</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>) <span class="type">int</span> x;
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-y</span><span class="delimiter">&quot;</span></span>) <span class="type">int</span> y;
}

<span class="type">class</span> <span class="class">App</span> {
    <span class="annotation">@Command</span>
    <span class="directive">public</span> <span class="type">void</span> doit(<span class="annotation">@Mixin</span> CommonParams params, <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-z</span><span class="delimiter">&quot;</span></span>) <span class="type">int</span> z) {}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the above example, the <code>-x</code> and <code>-y</code> options are added to the other options of the <code>doit</code> command.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="spec-annotation">20.3. <a id="_spec-annotation"></a> <code>@Spec</code> Annotation</h3>
<div class="paragraph">
<p>Picocli 3.2 introduces a <code>@Spec</code> annotation for injecting the <code>CommandSpec</code> model of the command into a command field.</p>
</div>
<div class="paragraph">
<p>This is useful when a command needs to use the picocli API, for example to walk the command hierarchy and iterate over its sibling commands.
This complements the <code>@ParentCommand</code> annotation;  the <code>@ParentCommand</code> annotation injects a user-defined command object, whereas this annotation injects a picocli class.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">InjectSpecExample</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span> {
   <span class="annotation">@Spec</span> CommandSpec commandSpec;

   <span class="comment">//...</span>

   <span class="directive">public</span> <span class="type">void</span> run() {
       <span class="comment">// do something with the injected spec</span>
   }
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_improved_support_for_chinese_japanese_and_korean">20.4. Improved Support for Chinese, Japanese and Korean</h3>
<div class="paragraph">
<p>Picocli will align the usage help message to fit within some user-defined width (80 columns by default).
A number of characters in Chinese, Japanese and Korean (CJK) are wider than others.
If those characters are treated to have the same width as other characters, the usage help message may extend past the right margin.</p>
</div>
<div class="paragraph">
<p>From 4.0, picocli will use 2 columns for these wide characters when calculating where to put line breaks, resulting in better usage help message text.</p>
</div>
<div class="paragraph">
<p>This can be switched off with <code>CommandLine.setAdjustLineBreaksForWideCJKCharacters(false)</code>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_custom_factory">20.5. Custom Factory</h3>
<div class="paragraph">
<p>Declaratively registered <a href="#_registering_subcommands_declaratively">subcommands</a>, <a href="#_option_specific_type_converters">type converters</a> and <a href="#_dynamic_version_information">version providers</a> must be instantiated somehow. From picocli 2.2, a custom factory can be specified when constructing a <code>CommandLine</code> instance. This allows full control over object creation and opens possibilities for Inversion of Control and Dependency Injection (see <a href="#_dependency_injection">next section</a>). For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">IFactory myFactory = getCustomFactory();
CommandLine cmdLine = <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> Git(), myFactory);</code></pre>
</div>
</div>
<div class="paragraph">
<p>Custom factories need to implement the <code>picocli.CommandLine.IFactory</code> interface:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">IFactory</span> {
    <span class="comment">/**
     * Creates and returns an instance of the specified class.
     * @param clazz the class to instantiate
     * @param &lt;K&gt; the type to instantiate
     * @return the new instance
     * @throws Exception an exception detailing what went wrong when creating the instance
     */</span>
    &lt;K&gt; K create(<span class="predefined-type">Class</span>&lt;K&gt; clazz) <span class="directive">throws</span> <span class="exception">Exception</span>;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If no factory is specified, a default factory is used. The default factory requires that the classes to instantiate have a public no-argument constructor: it instantiates the class by calling first calling <code>clazz.newInstance()</code>, and if that fails, <code>clazz.getDeclaredConstructor().newInstance()</code>.</p>
</div>
<div class="paragraph">
<p>From version 4.0, picocli delegates all object creation to the factory, including creating <code>Collection</code> instances to capture <a href="#_arrays_and_collections">multi-value</a> <code>@Option</code> values.
Previously, <code>Collection</code> objects were instantiated separately without involving the factory.</p>
</div>
<div class="paragraph">
<p>It is recommended that custom factories should fall back to the default factory. Something like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Override</span>
<span class="directive">public</span> &lt;K&gt; K create(<span class="predefined-type">Class</span>&lt;K&gt; clazz) <span class="directive">throws</span> <span class="exception">Exception</span> {
    <span class="keyword">try</span> {
        <span class="keyword">return</span> doCreate(clazz); <span class="comment">// custom factory lookup or instantiation</span>
    } <span class="keyword">catch</span> (<span class="exception">Exception</span> e) {
        <span class="keyword">return</span> CommandLine.defaultFactory().create(clazz); <span class="comment">// fallback if missing</span>
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_boolean_options_with_parameters">20.6. Boolean Options with Parameters</h3>
<div class="paragraph">
<p>By default the value of a boolean field is set to the logical negative of its default value when the option is specified on the command line.</p>
</div>
<div class="paragraph">
<p>It is possible to let end users explicitly specify "true" or "false" as a parameter for a boolean option by defining an explicit <a href="#_arity">Arity</a> attribute. A boolean option with <code>arity = "0..1"</code> accepts zero to one parameters, <code>arity = "1"</code> means the option <em>must</em> have one parameter. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">BooleanOptionWithParameters</span> {
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>, arity = <span class="string"><span class="delimiter">&quot;</span><span class="content">1</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">1 mandatory parameter</span><span class="delimiter">&quot;</span></span>)
    <span class="type">boolean</span> x;

    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-y</span><span class="delimiter">&quot;</span></span>, arity = <span class="string"><span class="delimiter">&quot;</span><span class="content">0..1</span><span class="delimiter">&quot;</span></span>, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">min 0 and max 1 parameter</span><span class="delimiter">&quot;</span></span>)
    <span class="type">boolean</span> y;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The following ways to invoke the program will be accepted (values are not case sensitive):</p>
</div>
<div class="listingblock">
<div class="content">
<pre>&lt;command&gt; -x true
&lt;command&gt; -x FALSE
&lt;command&gt; -x TRUE -y
&lt;command&gt; -x True -y False</pre>
</div>
</div>
<div class="paragraph">
<p>But trying to specify the <code>-x</code> option without a parameter, or with a value other than "true" or "false" (case insensitive) will result in a <code>ParameterException</code>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_hexadecimal_values">20.7. Hexadecimal Values</h3>
<div class="paragraph">
<p>Numeric values are interpreted as decimal numbers by default. If you want picocli to be more flexible, you can
register a custom type converter that delegates to the <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html#decode-java.lang.String-">decode</a> method to convert strings to numbers.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The <code>decode</code> method looks at the prefix to determine the radix, so numbers
starting with <code>0x</code>, <code>0X</code> or <code>#</code> are interpreted as hexadecimal numbers, numbers starting with <code>0</code> are interpreted
as octal numbers, and otherwise the number is interpreted as a decimal number.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Java 8-style lambdas:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">new</span> CommandLine(obj)
        .registerConverter(<span class="predefined-type">Byte</span>.class,    s -&gt; <span class="predefined-type">Byte</span>::decode)
        .registerConverter(<span class="predefined-type">Byte</span>.TYPE,     s -&gt; <span class="predefined-type">Byte</span>::decode)
        .registerConverter(<span class="predefined-type">Short</span>.class,   s -&gt; <span class="predefined-type">Short</span>::decode)
        .registerConverter(<span class="predefined-type">Short</span>.TYPE,    s -&gt; <span class="predefined-type">Short</span>::decode)
        .registerConverter(<span class="predefined-type">Integer</span>.class, s -&gt; <span class="predefined-type">Integer</span>::decode)
        .registerConverter(<span class="predefined-type">Integer</span>.TYPE,  s -&gt; <span class="predefined-type">Integer</span>::decode)
        .registerConverter(<span class="predefined-type">Long</span>.class,    s -&gt; <span class="predefined-type">Long</span>::decode)
        .registerConverter(<span class="predefined-type">Long</span>.TYPE,     s -&gt; <span class="predefined-type">Long</span>::decode);</code></pre>
</div>
</div>
<div class="paragraph">
<p>In Java 5:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">ITypeConverter&lt;<span class="predefined-type">Integer</span>&gt; intConverter = <span class="keyword">new</span> ITypeConverter&lt;<span class="predefined-type">Integer</span>&gt;() {
    <span class="directive">public</span> <span class="predefined-type">Integer</span> convert(<span class="predefined-type">String</span> s) {
        <span class="keyword">return</span> <span class="predefined-type">Integer</span>.decode(s);
    }
};
commandLine.registerConverter(<span class="predefined-type">Integer</span>.class, intConverter);
commandLine.registerConverter(<span class="predefined-type">Integer</span>.TYPE,  intConverter);
...</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_option_parameter_separators_2">20.8. Option-Parameter Separators</h3>
<div class="sect3">
<h4 id="_default_separators">20.8.1. Default Separators</h4>
<div class="paragraph">
<p>Options may take an <em>option parameter</em> (also called <em>option-argument</em>).
For POSIX-style short options (like <code>-f</code> or <code>-c</code>), the option parameter may be attached to the option,
or it may be separated by a space or the <em>separator string</em> (<code>=</code> by default).
That is, all of the below are equivalent:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">&lt;command&gt; -foutput.txt
&lt;command&gt; -f output.txt
&lt;command&gt; -f=output.txt</code></pre>
</div>
</div>
<div class="paragraph">
<p>Long option names (like <code>--file</code>) must be separated from their option parameter by a space or the
<em>separator string</em> (<code>=</code> by default). That is, the first two below examples are valid but the last example is invalid:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="comment">// valid (separator between --file and its parameter)</span>
&lt;command&gt; --file output.txt
&lt;command&gt; --file=output.txt

<span class="comment">// invalid (picocli will not recognize the --file option when attached to its parameter)</span>
&lt;command&gt; --fileoutput.txt</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_custom_separators">20.8.2. Custom Separators</h4>
<div class="paragraph">
<p>The separator string can be customized programmatically or declaratively.</p>
</div>
<div class="paragraph">
<p>Use the <code>separator</code> attribute of the <code>@Command</code> annotation to declaratively set a separator string:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>(separator = <span class="string"><span class="delimiter">&quot;</span><span class="content">:</span><span class="delimiter">&quot;</span></span>)  <span class="comment">// declaratively set a separator</span>
<span class="type">class</span> <span class="class">OptionArg</span> {
    <span class="annotation">@Option</span>(names = { <span class="string"><span class="delimiter">&quot;</span><span class="content">-f</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--file</span><span class="delimiter">&quot;</span></span> }) <span class="predefined-type">String</span> file;
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">OptionArg optionArg = CommandLine.populateCommand(<span class="keyword">new</span> OptionArg(), <span class="string"><span class="delimiter">&quot;</span><span class="content">-f:output.txt</span><span class="delimiter">&quot;</span></span>);
<span class="keyword">assert</span> optionArg.file.equals(<span class="string"><span class="delimiter">&quot;</span><span class="content">output.txt</span><span class="delimiter">&quot;</span></span>);</code></pre>
</div>
</div>
<div class="paragraph">
<p>Alternatively, the separator string can be changed programmatically with the <code>CommandLine.setSeparator(String separator)</code> method.
For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">OptionArg optionArg     = <span class="keyword">new</span> OptionArg();
CommandLine commandLine = <span class="keyword">new</span> CommandLine(optionArg);

commandLine.setSeparator(<span class="string"><span class="delimiter">&quot;</span><span class="content">:</span><span class="delimiter">&quot;</span></span>); <span class="comment">// programmatically set a separator</span>
commandLine.parseArgs(<span class="string"><span class="delimiter">&quot;</span><span class="content">-f:output.txt</span><span class="delimiter">&quot;</span></span>);
<span class="keyword">assert</span> optionArg.file.equals(<span class="string"><span class="delimiter">&quot;</span><span class="content">output.txt</span><span class="delimiter">&quot;</span></span>);</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_best_practices_for_command_line_interfaces">20.9. Best Practices for Command Line Interfaces</h3>
<div class="paragraph">
<p>When designing your command line application,
the <a href="https://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html#Command_002dLine-Interfaces">GNU recommendations</a> for command line interfaces and <a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_02">POSIX Utility Guidelines</a> may be useful.</p>
</div>
<div class="paragraph">
<p>Generally, many applications use options for optional values and parameters for mandatory values.
However, picocli lets you make options required if you want to, see <a href="#_required_arguments">Required Arguments</a>.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_dependency_injection">21. Dependency Injection</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_guice_example">21.1. Guice Example</h3>
<div class="paragraph">
<p><span class="image"><img src="https://picocli.info/images/225px-Guice.jpg" alt="Guice logo"></span></p>
</div>
<div class="paragraph">
<p>The below example shows how to create a <a href="#_custom_factory">custom <code>IFactory</code></a> implementation with a Guice <code>Injector</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">com.google.inject</span>.*;
<span class="keyword">import</span> <span class="include">picocli.CommandLine.IFactory</span>;

<span class="directive">public</span> <span class="type">class</span> <span class="class">GuiceFactory</span> <span class="directive">implements</span> IFactory {
    <span class="directive">private</span> <span class="directive">final</span> Injector injector = Guice.createInjector(<span class="keyword">new</span> DemoModule());

    <span class="annotation">@Override</span>
    <span class="directive">public</span> &lt;K&gt; K create(<span class="predefined-type">Class</span>&lt;K&gt; aClass) <span class="directive">throws</span> <span class="exception">Exception</span> {
        <span class="keyword">try</span> {
            <span class="keyword">return</span> injector.getInstance(aClass);
        } <span class="keyword">catch</span> (<span class="exception">ConfigurationException</span> ex) { <span class="comment">// no implementation found in Guice configuration</span>
            <span class="keyword">return</span> CommandLine.defaultFactory().create(clazz); <span class="comment">// fallback if missing</span>
        }
    }

    <span class="directive">static</span> <span class="type">class</span> <span class="class">DemoModule</span> <span class="directive">extends</span> AbstractModule {
        <span class="annotation">@Override</span>
        <span class="directive">protected</span> <span class="type">void</span> configure() {
            bind(java.util.List.class).to(java.util.LinkedList.class);
            bind(<span class="predefined-type">Runnable</span>.class).to(InjectionDemo.class);
        }
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Use the custom factory when creating a <code>CommandLine</code> instance, or when invoking the <code>run</code> or <code>call</code> convenience methods:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">javax.inject.Inject</span>;

<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">di-demo</span><span class="delimiter">&quot;</span></span>)
<span class="directive">public</span> <span class="type">class</span> <span class="class">InjectionDemo</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span> {
    <span class="annotation">@Inject</span> java.util.List list;

    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>) <span class="type">int</span> x;

    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) {
        <span class="keyword">new</span> CommandLine(<span class="predefined-type">Runnable</span>.class, <span class="keyword">new</span> GuiceFactory()).execute(args);
    }

    <span class="annotation">@Override</span>
    <span class="directive">public</span> <span class="type">void</span> run() {
        <span class="keyword">assert</span> list <span class="keyword">instanceof</span> java.util.LinkedList;
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_spring_boot_example">21.2. Spring Boot Example</h3>
<div class="paragraph">
<p><span class="image"><img src="https://picocli.info/images/spring-boot.png" alt="Spring Boot Logo" width="350" height="167"></span></p>
</div>
<div class="paragraph">
<p>From 4.0, picocli provides a custom factory in the <code>picocli-spring-boot-starter</code> module.
To use this custom factory, add the following dependency:</p>
</div>
<div class="paragraph">
<p>Maven:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;dependency&gt;</span>
  <span class="tag">&lt;groupId&gt;</span>info.picocli<span class="tag">&lt;/groupId&gt;</span>
  <span class="tag">&lt;artifactId&gt;</span>picocli-spring-boot-starter<span class="tag">&lt;/artifactId&gt;</span>
  <span class="tag">&lt;version&gt;</span>4.2.0<span class="tag">&lt;/version&gt;</span>
<span class="tag">&lt;/dependency&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Gradle:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>dependencies {
    compile "info.picocli:picocli-spring-boot-starter:4.2.0"
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will bring in the <code>info.picocli:picocli</code> and <code>org.springframework.boot:spring-boot-starter</code> dependencies.</p>
</div>
<div class="paragraph">
<p>The below example shows how to use picocli with Spring Boot:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">org.springframework.beans.factory.annotation.Autowired</span>;
<span class="keyword">import</span> <span class="include">org.springframework.boot.CommandLineRunner</span>;
<span class="keyword">import</span> <span class="include">org.springframework.boot.ExitCodeGenerator</span>;
<span class="keyword">import</span> <span class="include">org.springframework.boot.autoconfigure.SpringBootApplication</span>;
<span class="keyword">import</span> <span class="include">org.springframework.boot.SpringApplication</span>;
<span class="keyword">import</span> <span class="include">org.springframework.context.annotation.Bean</span>;
<span class="keyword">import</span> <span class="include">picocli.CommandLine</span>;
<span class="keyword">import</span> <span class="include">picocli.CommandLine.IFactory</span>;

<span class="annotation">@SpringBootApplication</span>
<span class="directive">public</span> <span class="type">class</span> <span class="class">MySpringApp</span> <span class="directive">implements</span> CommandLineRunner, ExitCodeGenerator {

    <span class="directive">private</span> IFactory factory;    <span class="comment">// auto-configured to inject PicocliSpringFactory</span>
    <span class="directive">private</span> MyCommand myCommand; <span class="comment">// your @picocli.CommandLine.Command-annotated class</span>
    <span class="directive">private</span> <span class="type">int</span> exitCode;

    <span class="comment">// constructor injection</span>
    MySpringApp(IFactory factory, MyCommand myCommand) {
        <span class="local-variable">this</span>.factory = factory;
        <span class="local-variable">this</span>.myCommand = myCommand;
    }

    <span class="annotation">@Override</span>
    <span class="directive">public</span> <span class="type">void</span> run(<span class="predefined-type">String</span>... args) {
        <span class="comment">// let picocli parse command line args and run the business logic</span>
        exitCode = <span class="keyword">new</span> CommandLine(myCommand, factory).execute(args);
    }

    <span class="annotation">@Override</span>
    <span class="directive">public</span> <span class="type">int</span> getExitCode() {
        <span class="keyword">return</span> exitCode;
    }

    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) {
        <span class="comment">// let Spring instantiate and inject dependencies</span>
        <span class="predefined-type">System</span>.exit(SpringApplication.exit(SpringApplication.run(MySpringApp.class, args)));
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>See the <a href="https://github.com/remkop/picocli/tree/master/picocli-spring-boot-starter">picocli-spring-boot-starter README</a> for another example.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
<div class="paragraph">
<p>It may be a good idea to define an option <code>--spring.config.location</code> in your command.
Spring Boot allows end users to specify the <code>spring.config.location</code> Spring environment property as a command line option to specify an alternative location for the <code>application.properties</code> file.
Defining this option prevents picocli from throwing an <code>UnmatchedArgumentException</code> ("Unknown option") when it sees an option it cannot match.
You can make it a <code>hidden</code> option so it is not shown in the usage help message, or add a description that explains its meaning.</p>
</div>
<div class="paragraph">
<p>Alternatively, you can define an <a href="#unmatched-annotation">unmatched</a> field to capture <em>all</em> unknown options (and positional parameters):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Unmatched</span> <span class="predefined-type">List</span>&lt;<span class="predefined-type">String</span>&gt; unmatched;</code></pre>
</div>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>When your command is annotated with <code>@org.springframework.stereotype.Component</code> Spring can autodetect it for dependency injection.
The business logic of your command looks like any other picocli command with options and parameters.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">org.springframework.stereotype.Component</span>;
<span class="keyword">import</span> <span class="include">org.springframework.beans.factory.annotation.Autowired</span>;
<span class="keyword">import</span> <span class="include">picocli.CommandLine.Command</span>;
<span class="keyword">import</span> <span class="include">picocli.CommandLine.Option</span>;
<span class="keyword">import</span> <span class="include">java.util.concurrent.Callable</span>;

<span class="annotation">@Component</span>
<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">myCommand</span><span class="delimiter">&quot;</span></span>)
<span class="directive">public</span> <span class="type">class</span> <span class="class">MyCommand</span> <span class="directive">implements</span> <span class="predefined-type">Callable</span>&lt;<span class="predefined-type">Integer</span>&gt; {

    <span class="annotation">@Autowired</span>
    <span class="directive">private</span> SomeService someService;

    <span class="comment">// Prevent &quot;Unknown option&quot; error when users use</span>
    <span class="comment">// the Spring Boot parameter 'spring.config.location' to specify</span>
    <span class="comment">// an alternative location for the application.properties file.</span>
    <span class="annotation">@Option</span>(names = <span class="string"><span class="delimiter">&quot;</span><span class="content">--spring.config.location</span><span class="delimiter">&quot;</span></span>, hidden = <span class="predefined-constant">true</span>)
    <span class="directive">private</span> <span class="predefined-type">String</span> springConfigLocation;

    <span class="annotation">@Option</span>(names = { <span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--option</span><span class="delimiter">&quot;</span></span> }, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">example option</span><span class="delimiter">&quot;</span></span>)
    <span class="directive">private</span> <span class="type">boolean</span> flag;

    <span class="directive">public</span> <span class="predefined-type">Integer</span> call() <span class="directive">throws</span> <span class="exception">Exception</span> {
        <span class="comment">// business logic here</span>
        <span class="keyword">return</span> <span class="integer">0</span>;
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_micronaut_example">21.3. Micronaut Example</h3>
<div class="paragraph">
<p><span class="image"><img src="https://micronaut.io/images/micronaut_mini_copy_tm.svg" alt="Micronaut Logo" width="350"></span></p>
</div>
<div class="paragraph">
<p>The Micronaut microservices framework provides <a href="https://docs.micronaut.io/latest/guide/index.html#picocli">built-in support</a> for picocli with its <code>PicocliRunner</code> class.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">io.micronaut.configuration.picocli.PicocliRunner</span>;
<span class="keyword">import</span> <span class="include">io.micronaut.http.annotation</span>.*;
<span class="keyword">import</span> <span class="include">io.micronaut.http.client</span>.*;
<span class="keyword">import</span> <span class="include">javax.inject.Inject</span>;

<span class="keyword">import</span> <span class="include">picocli.CommandLine.Command</span>;
<span class="keyword">import</span> <span class="include">picocli.CommandLine.Option</span>;

<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">myMicronautApp</span><span class="delimiter">&quot;</span></span>)
<span class="directive">public</span> <span class="type">class</span> <span class="class">MyMicronautApp</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span> {

    <span class="annotation">@Client</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">https://api.github.com</span><span class="delimiter">&quot;</span></span>)
    <span class="annotation">@Inject</span> RxHttpClient client;

    <span class="annotation">@Option</span>(names = {<span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--option</span><span class="delimiter">&quot;</span></span>}, description = <span class="string"><span class="delimiter">&quot;</span><span class="content">example option</span><span class="delimiter">&quot;</span></span>)
    <span class="type">boolean</span> flag;

    <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) <span class="directive">throws</span> <span class="exception">Exception</span> {
        <span class="comment">// let Micronaut instantiate and inject services</span>
        PicocliRunner.run(MyMicronautApp.class, args);
    }

    <span class="directive">public</span> <span class="type">void</span> run() {
        <span class="comment">// business logic here</span>
    }
}</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_java_9_jpms_modules">22. Java 9 JPMS Modules</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The main <code>picocli-${version}.jar</code> is a JPMS module named <code>info.picocli</code>.</p>
</div>
<div class="paragraph">
<p>Starting from picocli 4.0, this jar will be an explicit module instead of an automatic module,
so the <a href="https://docs.oracle.com/en/java/javase/12/tools/jlink.html"><code>jlink</code> tool</a> can be used to provide a trimmed binary image that has only the required modules.
(Note that <a href="https://medium.com/azulsystems/using-jlink-to-build-java-runtimes-for-non-modular-applications-9568c5e70ef4">there are ways</a> to use jlink with non-modular applications.)</p>
</div>
<div class="paragraph">
<p>Typically, a modular jar includes the <code>module-info.class</code> file in its root directory.
This causes problems for some older tools, which incorrectly process the module descriptor as if it were a normal Java class.
To provide the best backward compatibility, the main picocli artifact is a <a href="https://openjdk.java.net/jeps/238#Modular-multi-release-JAR-files">modular multi-release jar</a> with the <code>module-info.class</code> file located in <code>META-INF/versions/9</code>.</p>
</div>
<div class="sect2">
<h3 id="_module_configuration">22.1. Module Configuration</h3>
<div class="paragraph">
<p>Applications that use Java 9&#8217;s modules need to configure their module to allow picocli reflective access to the annotated classes and fields.</p>
</div>
<div class="paragraph">
<p>Often applications want the annotated classes and fields to be <strong>private</strong>; there should be no need to make them part of the exported API of your module just to allow picocli to access them. The below settings make this possible.</p>
</div>
<div class="paragraph">
<p>Example <code>module-info.java</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>module com.yourorg.yourapp {
   requires info.picocli;

   // Open this package for reflection to external frameworks.
   opens your.package.using.picocli;

   // or: limit access to picocli only
   opens other.package.using.picocli to info.picocli;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that neither package is <code>exported</code>, so other modules cannot accidentally compile against types in these packages.</p>
</div>
<div class="paragraph">
<p>Alternatively:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>// open all packages in the module to reflective access
open module com.yourorg.yourapp {
   requires info.picocli;
}</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_osgi_bundle">23. OSGi Bundle</h2>
<div class="sectionbody">
<div class="paragraph">
<p><span class="image"><img src="https://www.osgi.org/wp-content/uploads/OSGi-website-header-logo.png" alt="OSGi logo"></span></p>
</div>
<div class="paragraph">
<p>From 4.0, the picocli JAR is an OSGi bundle with <code>Bundle-Name: picocli</code> and other appropriate metadata in the manifest.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_tracing">24. Tracing</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Picocli 1.0 introduced support for parser tracing to facilitate troubleshooting.</p>
</div>
<div class="paragraph">
<p>System property <code>picocli.trace</code> controls the trace level. Supported levels are <code>OFF</code>, <code>WARN</code>, <code>INFO</code>, and <code>DEBUG</code>. The default trace level is <code>WARN</code>.</p>
</div>
<div class="paragraph">
<p>Specifying system property <code>-Dpicocli.trace</code> without a value will set the trace level to <code>INFO</code>.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>DEBUG: Shows details of the decisions made by the parser during command line parsing.</p>
</li>
<li>
<p>INFO: Shows a high-level overview of what happens during command line parsing.</p>
</li>
<li>
<p>WARN: The default. Shows warnings instead of errors when lenient parsing is enabled:
when single-value options were specified multiple times (and <code>CommandLine.overwrittenOptionsAllowed</code> is <code>true</code>),
or when command line arguments could not be matched as an option or positional parameter
(and <code>CommandLine.unmatchedArgumentsAllowed</code> is <code>true</code>).</p>
</li>
<li>
<p>OFF: Suppresses all tracing including warnings.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="bash"># create a custom 'git' command that invokes picocli.Demo$Git with tracing switched on
alias git='java -Dpicocli.trace -cp picocli-all.jar picocli.Demo$Git'

# invoke our command with some parameters
git --git-dir=/home/rpopma/picocli commit -m &quot;Fixed typos&quot; -- src1.java src2.java src3.java

# remove our 'git' pseudonym from the current shell environment
unalias git</code></pre>
</div>
</div>
<div class="paragraph">
<p>Output:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>[picocli INFO] Parsing 8 command line args [--git-dir=/home/rpopma/picocli, commit, -m, "Fixed typos", --, src1.java, src2.java, src3.java]
[picocli INFO] Setting File field 'Git.gitDir' to '\home\rpopma\picocli' for option --git-dir
[picocli INFO] Adding [Fixed typos] to List&lt;String&gt; field 'GitCommit.message' for option -m
[picocli INFO] Found end-of-options delimiter '--'. Treating remainder as positional parameters.
[picocli INFO] Adding [src1.java] to List&lt;String&gt; field 'GitCommit.files' for args[0..*]
[picocli INFO] Adding [src2.java] to List&lt;String&gt; field 'GitCommit.files' for args[0..*]
[picocli INFO] Adding [src3.java] to List&lt;String&gt; field 'GitCommit.files' for args[0..*]</pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_tab_autocomplete">25. TAB Autocomplete</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Picocli-based applications can now have command line completion in Bash or Zsh Unix shells.
See the <a href="autocomplete.html">Autocomplete for Java Command Line Applications</a> manual for how to generate an autocompletion script tailored to your application.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_generate_man_page_documentation">26. Generate Man Page Documentation</h2>
<div class="sectionbody">
<div class="paragraph">
<p>From picocli 4.2, the <code>picocli-codegen</code> module has a <code>ManPageGenerator</code> tool that can generate AsciiDoc documentation using the <code>manpage</code> doctype and manpage document structure.
The generated AsciiDoc files can be converted to HTML, PDF and unix man pages with the wonderful <a href="https://asciidoctor.org/docs/user-manual/#man-pages">asciidoctor</a> tool.</p>
</div>
<div class="paragraph">
<p>See the <a href="https://github.com/remkop/picocli/tree/master/picocli-codegen#generate-documentation">Generate Documentation</a> section of the <a href="https://github.com/remkop/picocli/tree/master/picocli-codegen">picocli-codegen README</a> for details on how to generate and customize this documentation.</p>
</div>
<div class="paragraph">
<p>The man pages for the picocli built-in tools were created with this tool:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="man/gen-manpage.html">gen-manpage</a> (<code>picocli.codegen.docgen.manpage.ManPageGenerator</code>)</p>
</li>
<li>
<p><a href="man/picocli.AutoComplete.html">picocli.AutoComplete</a> (<code>picocli.AutoComplete</code>)</p>
</li>
<li>
<p><a href="man/generate-completion.html">generate-completion</a> (<code>picocli.AutoComplete$GenerateCompletion</code> - to be used as a subcommand)</p>
</li>
<li>
<p><a href="man/gen-reflect-config.html">gen-reflect-config</a> (<code>picocli.codegen.aot.graalvm.ReflectionConfigGenerator</code>)</p>
</li>
<li>
<p><a href="man/gen-proxy-config.html">gen-proxy-config</a> (<code>picocli.codegen.aot.graalvm.DynamicProxyConfigGenerator</code>)</p>
</li>
<li>
<p><a href="man/gen-resource-config.html">gen-resource-config</a> (<code>picocli.codegen.aot.graalvm.ResourceConfigGenerator</code>)</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_testing_your_application">27. Testing Your Application</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_black_box_and_white_box_testing">27.1. Black Box and White Box Testing</h3>
<div class="paragraph">
<p>Picocli 4.0 introduced the <a href="#execute"><code>execute</code></a>, <code>get/setOut</code>, and <code>get/setErr</code> APIs that make testing a lot easier.</p>
</div>
<div class="paragraph">
<p>Applications can do black box testing by verifying the exit code and the output of the program to the standard output stream and standard error stream.</p>
</div>
<div class="paragraph">
<p>Additionally, you can do white box testing by keeping a reference to the application and asserting on its state after giving it various command line inputs.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">MyApp app = <span class="keyword">new</span> MyApp();
CommandLine cmd = <span class="keyword">new</span> CommandLine(app);

<span class="predefined-type">StringWriter</span> sw = <span class="keyword">new</span> <span class="predefined-type">StringWriter</span>();
cmd.setOut(<span class="keyword">new</span> <span class="predefined-type">PrintWriter</span>(sw));

<span class="comment">// black box testing</span>
<span class="type">int</span> exitCode = cmd.execute(<span class="string"><span class="delimiter">&quot;</span><span class="content">-x</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">-y=123</span><span class="delimiter">&quot;</span></span>);
assertEquals(<span class="integer">0</span>, exitCode);
assertEquals(<span class="string"><span class="delimiter">&quot;</span><span class="content">Your output is abc...</span><span class="delimiter">&quot;</span></span>, sw.toString());

<span class="comment">// white box testing</span>
assertEquals(<span class="string"><span class="delimiter">&quot;</span><span class="content">expectedValue1</span><span class="delimiter">&quot;</span></span>, app.getState1());
assertEquals(<span class="string"><span class="delimiter">&quot;</span><span class="content">expectedValue2</span><span class="delimiter">&quot;</span></span>, app.getState2());</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_testing_the_output">27.2. Testing the Output</h3>
<div class="paragraph">
<p>This assumes that the application uses the <code>PrintWriter</code> provided by <a href="https://picocli.info/apidocs/picocli/CommandLine.html#getOut--"><code>CommandLine.getOut</code></a> or  <a href="https://picocli.info/apidocs/picocli/CommandLine.html#getErr--"><code>CommandLine.getErr</code></a>.
Applications can get these writers via the <a href="#spec-annotation"><code>@Spec</code></a> annotation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Command</span>
<span class="type">class</span> <span class="class">MyApp</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span> {
    <span class="annotation">@Spec</span> CommandSpec spec;

    <span class="directive">public</span> <span class="type">void</span> run() {
        <span class="comment">// make testing easier by printing to the Err and Out streams provided by picocli</span>
        spec.commandLine().getOut().println(<span class="string"><span class="delimiter">&quot;</span><span class="content">Your output is abc...</span><span class="delimiter">&quot;</span></span>);
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Applications that use a version of picocli older than 4.0, or applications that print to <code>System.out</code> or <code>System.err</code> directly can be tested by capturing the standard output and error streams like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">ByteArrayOutputStream</span> err = <span class="keyword">new</span> <span class="predefined-type">ByteArrayOutputStream</span>();
<span class="predefined-type">ByteArrayOutputStream</span> out = <span class="keyword">new</span> <span class="predefined-type">ByteArrayOutputStream</span>();
<span class="predefined-type">PrintStream</span> oldErr = <span class="predefined-type">System</span>.err;
<span class="predefined-type">PrintStream</span> oldOut = <span class="predefined-type">System</span>.out;
<span class="keyword">try</span> {
    <span class="predefined-type">System</span>.setErr(<span class="keyword">new</span> <span class="predefined-type">PrintStream</span>(err));           <span class="comment">// setup</span>
    <span class="predefined-type">System</span>.setOut(<span class="keyword">new</span> <span class="predefined-type">PrintStream</span>(out));
    <span class="predefined-type">String</span><span class="type">[]</span> args = <span class="string"><span class="delimiter">&quot;</span><span class="content">my command args</span><span class="delimiter">&quot;</span></span>.split(<span class="string"><span class="delimiter">&quot;</span><span class="content"> </span><span class="delimiter">&quot;</span></span>);  <span class="comment">// test</span>
    <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MyApp()).execute(args);
} <span class="keyword">finally</span> {
    <span class="predefined-type">System</span>.setErr(oldErr);                         <span class="comment">// teardown</span>
    <span class="predefined-type">System</span>.setOut(oldOut);
}
assertEquals(<span class="string"><span class="delimiter">&quot;</span><span class="content">MY COMMAND OUTPUT</span><span class="delimiter">&quot;</span></span>, out.toString()); <span class="comment">// verify</span>
assertEquals(<span class="string"><span class="delimiter">&quot;</span><span class="delimiter">&quot;</span></span>, err.toString());</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you&#8217;re testing with JUnit 4, you can do the setup in a <code>@org.junit.Before</code>-annotated method and teardown in an <code>@org.junit.After</code>-annotated method.
The JUnit 5 equivalent annotations are <code>@org.junit.jupiter.api.BeforeEach</code> and <code>@org.junit.jupiter.api.AfterEach</code>, respectively.
For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="comment">//import org.junit.After;  // JUnit 4</span>
<span class="comment">//import org.junit.Before; // JUnit 4</span>
<span class="keyword">import</span> <span class="include">org.junit.jupiter.api.AfterEach</span>;  <span class="comment">// JUnit 5</span>
<span class="keyword">import</span> <span class="include">org.junit.jupiter.api.BeforeEach</span>; <span class="comment">// JUnit 5</span>
<span class="comment">//...</span>
<span class="type">class</span> <span class="class">TestOutput</span> {
    <span class="directive">final</span> <span class="predefined-type">PrintStream</span> originalOut = <span class="predefined-type">System</span>.out;
    <span class="directive">final</span> <span class="predefined-type">PrintStream</span> originalErr = <span class="predefined-type">System</span>.err;
    <span class="directive">final</span> <span class="predefined-type">ByteArrayOutputStream</span> out = <span class="keyword">new</span> <span class="predefined-type">ByteArrayOutputStream</span>();
    <span class="directive">final</span> <span class="predefined-type">ByteArrayOutputStream</span> err = <span class="keyword">new</span> <span class="predefined-type">ByteArrayOutputStream</span>();

    <span class="comment">//@Before   // JUnit 4</span>
    <span class="annotation">@BeforeEach</span> <span class="comment">// JUnit 5</span>
    <span class="directive">public</span> <span class="type">void</span> setUpStreams() {
        out.reset();
        err.reset();
        <span class="predefined-type">System</span>.setOut(<span class="keyword">new</span> <span class="predefined-type">PrintStream</span>(out));
        <span class="predefined-type">System</span>.setErr(<span class="keyword">new</span> <span class="predefined-type">PrintStream</span>(err));
    }

    <span class="comment">//@After   // JUnit 4</span>
    <span class="annotation">@AfterEach</span> <span class="comment">// JUnit 5</span>
    <span class="directive">public</span> <span class="type">void</span> restoreStreams() {
        <span class="predefined-type">System</span>.setOut(originalOut);
        <span class="predefined-type">System</span>.setErr(originalErr);
    }

    <span class="annotation">@Test</span>
    <span class="directive">public</span> <span class="type">void</span> test() {
        <span class="predefined-type">String</span><span class="type">[]</span> args = <span class="string"><span class="delimiter">&quot;</span><span class="content">my command args</span><span class="delimiter">&quot;</span></span>.split(<span class="string"><span class="delimiter">&quot;</span><span class="content"> </span><span class="delimiter">&quot;</span></span>);
        <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MyApp()).execute(args);
        assertEquals(<span class="string"><span class="delimiter">&quot;</span><span class="content">MY COMMAND OUTPUT</span><span class="delimiter">&quot;</span></span>, out.toString());
        assertEquals(<span class="string"><span class="delimiter">&quot;</span><span class="delimiter">&quot;</span></span>, err.toString());
    }
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_testing_the_exit_code">27.3. Testing the Exit Code</h3>
<div class="paragraph">
<p>Testing the exit code of applications that call <code>System.exit</code> can be tricky but is not impossible.</p>
</div>
<div class="paragraph">
<p>Applications that use JUnit 4 can use Stephan Birkner&#8217;s  <a href="https://stefanbirkner.github.io/system-rules">System-Rules</a> project for testing the  <a href="https://stefanbirkner.github.io/system-rules/#ExpectedSystemExit">exit code</a>.
(This library has many other nice features, including capturing the standard output and standard error <a href="https://stefanbirkner.github.io/system-rules/#SystemErrAndOutRule">streams</a>, and more.)
For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">org.junit.Rule</span>;
<span class="keyword">import</span> <span class="include">org.junit.Test</span>;
<span class="keyword">import</span> <span class="include">org.junit.contrib.java.lang.system.ExpectedSystemExit</span>;

<span class="type">class</span> <span class="class">MyTest</span> {
    <span class="annotation">@Rule</span> <span class="directive">public</span> <span class="directive">final</span> ExpectedSystemExit exit = ExpectedSystemExit.none();

    <span class="annotation">@Test</span>
    <span class="directive">public</span> <span class="type">void</span> testExitCode() {
        <span class="annotation">@Command</span> <span class="type">class</span> <span class="class">App</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span> {
            <span class="directive">public</span> <span class="type">void</span> run() {
                <span class="predefined-type">System</span>.exit(<span class="integer">23</span>);
            }
        }
        exit.expectSystemExitWithStatus(<span class="integer">23</span>);
        <span class="keyword">new</span> CommandLine(<span class="keyword">new</span> App()).execute();
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>JUnit 5 users may be interested in Todd Ginsberg&#8217;s blog post <a href="https://todd.ginsberg.com/post/testing-system-exit/">Testing System.exit() with JUnit5</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_testing_environment_variables">27.4. Testing Environment Variables</h3>
<div class="paragraph">
<p>Since picocli offers support for using <a href="#_variable_interpolation">environment variables</a> in the annotations, you may want to test this.</p>
</div>
<div class="paragraph">
<p>Applications that use JUnit 4 can use Stephan Birkner&#8217;s  <a href="https://stefanbirkner.github.io/system-rules">System-Rules</a> project for <a href="https://stefanbirkner.github.io/system-rules/#EnvironmentVariables">testing environment variables</a>.</p>
</div>
<div class="paragraph">
<p>JUnit 5 does not appear to provide an equivalent extension for testing environment variables.
JUnit 5 users can use Stephan Birkner&#8217;s <code>@Rule EnvironmentVariables &#8230;&#8203;</code> for testing environment variables, but there are some things to be aware of.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Use <code>com.github.stefanbirkner:system-rules</code> version 1.17.2: the latest version, 1.18, has an <a href="https://github.com/stefanbirkner/system-rules/issues/70">issue</a> that means the Environment Variables rule will not work in JUnit 5.</p>
</li>
<li>
<p><a href="https://github.com/remkop/picocli/issues/976#issuecomment-601200999">Apparently</a> the JUnit 5 <a href="https://junit.org/junit5/docs/current/user-guide/#migrating-from-junit4-rule-support"><code>@EnableRuleMigrationSupport</code> annotation</a> is not sufficient to reliably use <code>@Rule EnvironmentVariables</code> in a JUnit 5 test.</p>
</li>
<li>
<p>Instead, I recommend creating a separate JUnit 4 test class for the environment variable tests.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In Gradle, use the following dependencies:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>dependencies {
    implementation      "info.picocli:picocli:${picocliVersion}"
    annotationProcessor "info.picocli:picocli-codegen:${picocliVersion}"

    testImplementation("com.github.stefanbirkner:system-rules:1.17.2") {
        exclude group:"junit"
    }
    testImplementation "junit:junit:${junit4Version}"
    testImplementation "org.junit.jupiter:junit-jupiter-api:${junit5Version}"

    testRuntimeOnly "org.junit.platform:junit-platform-launcher:1.6.0"
    testRuntimeOnly "org.junit.vintage:junit-vintage-engine:${junit5Version}"
    testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine:${junit5Version}"

    // ...
}

test {
    useJUnitPlatform {
        includeEngines 'junit-jupiter', 'junit-vintage'
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>For more details, see the <a href="https://github.com/remkop/picocli/files/4359943/bulk-scripts-public.zip">sample project</a> provided by David M. Carr.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_packaging_your_application">28. Packaging Your Application</h2>
<div class="sectionbody">
<div class="paragraph">
<p>You finished your application. Congratulations! Now, how do you package it and distribute it to your users? Here are some ideas.</p>
</div>
<div class="sect2">
<h3 id="_graalvm_native_image">28.1. GraalVM Native Image</h3>
<div class="paragraph">
<p><span class="image"><img src="images/exe-picocli-on-graalvm.png" alt="Turn your picocli-based application into a native image" width="265" height="150"></span></p>
</div>
<div class="sect3">
<h4 id="_what_are_graalvm_native_images">28.1.1. What are GraalVM Native Images?</h4>
<div class="paragraph">
<p><a href="https://www.graalvm.org/docs/reference-manual/aot-compilation/">GraalVM Native Image</a> allows you to
ahead-of-time compile Java code to a standalone executable, called a native image.
The resulting executable includes the application, the libraries, and the JDK and does not require a separate Java VM to be installed.
The generated native image has faster startup time and lower runtime memory overhead compared to a Java VM.</p>
</div>
<div class="paragraph">
<p>GraalVM native images have some limitations and require some extra <a href="https://github.com/oracle/graal/blob/master/substratevm/CONFIGURE.md">configuration</a>
to be able to use features like <a href="https://github.com/oracle/graal/blob/master/substratevm/REFLECTION.md">reflection</a>, <a href="https://github.com/oracle/graal/blob/master/substratevm/RESOURCES.md">resources</a> (including resource bundles) and <a href="https://github.com/oracle/graal/blob/master/substratevm/DYNAMIC_PROXY.md">dynamic proxies</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_how_do_i_create_a_native_image_for_my_application">28.1.2. How do I Create a Native Image for my Application?</h4>
<div class="paragraph">
<p>The <code>picocli-codegen</code> module contains an annotation processor that generates the necessary configuration files
under <code>META-INF/native-image/picocli-generated/$project</code> during compilation,
to be included in the application jar. The <a href="#_annotation_processor">Annotation Processor</a> section of the manual has details on configuring the annotation processor, and further information can be found in the <a href="https://github.com/remkop/picocli/tree/master/picocli-codegen">picocli-codegen README</a>
file.</p>
</div>
<div class="paragraph">
<p>By embedding these configuration files, your jar is instantly Graal-enabled: the
<a href="https://www.graalvm.org/docs/reference-manual/aot-compilation/#install-native-image"><code>native-image</code> tool</a>
used to generate the native executable is able to get the configuration from the jar.
In most cases no further configuration is needed when generating a native image.</p>
</div>
<div class="paragraph">
<p>After installing GraalVM and installing the <code>native-image</code> generator utility (with <code>gu install -L /path/to/native-image-installable</code>),
you can then create a native image by invoking the <code>native-image</code> command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>path/to/native-image -cp picocli-4.2.0.jar --static -jar myapp.jar</pre>
</div>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
To create a native image, the compiler toolchain for your platform needs to be installed. See <a href="https://www.infoq.com/articles/java-native-cli-graalvm-picocli/">Build Great Native CLI Apps in Java with Graalvm and Picocli</a> for details.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>GraalVM includes a <a href="https://medium.com/graalvm/simplifying-native-image-generation-with-maven-plugin-and-embeddable-configuration-d5b283b92f57">Maven plugin</a>
to generate a native image during the build.
Gradle users may be interested in the <a href="https://github.com/palantir/gradle-graal">gradle-graal</a> plugin by Palantir, or the <a href="https://plugins.gradle.org/plugin/org.mikeneck.graalvm-native-image">graalvm-native-image</a> plugin by Mike Neck.
(Documentation for both Maven and Gradle plugins seems sparse at time of this writing.)</p>
</div>
</div>
<div class="sect3">
<h4 id="_where_can_i_get_more_details">28.1.3. Where can I get More Details?</h4>
<div class="paragraph">
<p>This InfoQ article <a href="https://www.infoq.com/articles/java-native-cli-graalvm-picocli/">Build Great Native CLI Apps in Java with Graalvm and Picocli</a> provides details on setting up the GraalVM toolchain for creating native images.
It pays special attention to Windows, where setting up the compiler toolchain can be tricky.</p>
</div>
<div class="paragraph">
<p>This <a href="https://picocli.info/picocli-on-graalvm.html">older article</a>, "Picocli on GraalVM: Blazingly Fast Command Line Apps", may still be useful.</p>
</div>
<div class="paragraph">
<p>See also this <a href="https://github.com/remkop/picocli-native-image-demo">demo Gradle project</a> and this <a href="https://github.com/remkop/picocli-native-image-maven-demo">demo Maven project</a> that provide a simple complete CLI app, with build instructions, that developers can clone, and build to get the stand-alone executable.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_build_tool_plugins">28.2. Build Tool Plugins</h3>
<div class="paragraph">
<p>Both <a href="https://www.mojohaus.org/appassembler/">Application Assembler Maven Plugin</a> and <a href="https://docs.gradle.org/current/userguide/application_plugin.html">Gradle Application plugin</a> create a distribution zip or tar file with launcher scripts. Both require a JRE to be installed on the target machine.</p>
</div>
</div>
<div class="sect2">
<h3 id="_launch4j">28.3. launch4j</h3>
<div class="paragraph">
<p><a href="http://launch4j.sourceforge.net/docs.html">launch4j</a> can create a native launcher executable. It can bundle a JRE (~200MB) or use a pre-installed one.</p>
</div>
</div>
<div class="sect2">
<h3 id="_javapackager_java_8">28.4. javapackager (Java 8)</h3>
<div class="paragraph">
<p>JDK 8 <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javapackager.html">javapackager</a> can create a native launcher executable. It can bundle a JRE (~200MB) or use a pre-installed one.</p>
</div>
</div>
<div class="sect2">
<h3 id="_jlink_java_9">28.5. jlink (Java 9+)</h3>
<div class="paragraph">
<p>With the JPMS module system introduced in Java 9 it became possible to use <a href="https://docs.oracle.com/javase/9/tools/jlink.htm#JSWOR-GUID-CECAC52B-CFEE-46CB-8166-F17A8E9280E9">jlink</a> to create a custom light-weight JRE with only the necessary modules.
This JRE may be as small as 30-40MB.
Use <code>jlink</code> with the <code>--launcher</code> option to generate launcher scripts for your application.</p>
</div>
<div class="paragraph">
<p>See <a href="https://medium.com/azulsystems/using-jlink-to-build-java-runtimes-for-non-modular-applications-9568c5e70ef4">this article</a> for using jlink for non-modular applications.</p>
</div>
</div>
<div class="sect2">
<h3 id="_jpackage_early_access">28.6. jpackage (Early Access)</h3>
<div class="paragraph">
<p><a href="https://jdk.java.net/jpackage/">jpackage</a> is an early access build of <a href="https://openjdk.java.net/jeps/343">JEP 343: Packaging Tool</a>.
JPackage can take the custom light-weight JRE produced by <code>jlink</code> and create an installer and a native application launcher.
The result is a Java "application image" that is a single directory in the filesystem containing
the native application launcher, resources and configuration files,
and the custom light-weight JRE runtime image (including the application modules) produced by <code>jlink</code>.</p>
</div>
<div class="paragraph">
<p>This <a href="https://www.infoq.com/news/2019/03/jep-343-jpackage/">InfoQ article</a> has more details.
Gradle users may like these plugins: <a href="https://badass-runtime-plugin.beryx.org/releases/latest/">org.beryx Badass Runtime Plugin</a>
and <a href="https://badass-jlink-plugin.beryx.org/releases/latest/">org.beryx Badass JLink Plugin</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_jbang">28.7. jbang</h3>
<div class="paragraph">
<p><a href="https://github.com/maxandersen/jbang">jbang</a> allows you to write scripts in Java that use external dependencies.
You use it with a <code>//DEPS</code> comment, similar to the <a href="http://groovy-lang.org/grape.html"><code>@Grab</code></a> annotation in Groovy.</p>
</div>
<div class="paragraph">
<p>Use <code>jbang --init=cli helloworld.java</code> to create an initial script with a picocli template.
This <a href="https://asciinema.org/a/AVwA19yijKRNKEO0bJENN2ME3?autoplay=true&amp;speed=2">asciinema presentation</a> shows what is possible.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_picocli_in_other_languages">29. Picocli in Other Languages</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Picocli may be used in other JVM languages that support annotations.</p>
</div>
<div class="sect2">
<h3 id="_groovy">29.1. Groovy</h3>
<div class="paragraph">
<p>In Groovy, use <code>[</code> and <code>]</code> to surround array values, instead of the <code>{</code> and <code>}</code> used in Java.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">MyApp</span><span class="delimiter">&quot;</span></span>, version = <span class="string"><span class="delimiter">&quot;</span><span class="content">Groovy picocli v4.0 demo</span><span class="delimiter">&quot;</span></span>,
         mixinStandardHelpOptions = <span class="predefined-constant">true</span>, <span class="comment">// add --help and --version options</span>
         description = <span class="string"><span class="delimiter">&quot;</span><span class="content">@|bold Groovy|@ @|underline picocli|@ example</span><span class="delimiter">&quot;</span></span>)
<span class="type">class</span> <span class="class">MyApp</span> <span class="directive">implements</span> <span class="predefined-type">Runnable</span> {

    <span class="annotation">@Option</span>(names = [<span class="string"><span class="delimiter">&quot;</span><span class="content">-c</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--count</span><span class="delimiter">&quot;</span></span>], description = <span class="string"><span class="delimiter">&quot;</span><span class="content">number of repetitions</span><span class="delimiter">&quot;</span></span>)
    <span class="type">int</span> count = <span class="integer">1</span>

    <span class="type">void</span> run() {
        count.times {
            println(<span class="string"><span class="delimiter">&quot;</span><span class="content">hello world </span><span class="inline"><span class="inline-delimiter">$</span><span class="local-variable">it</span></span><span class="content">...</span><span class="delimiter">&quot;</span></span>)
        }
    }
    <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) {
        <span class="predefined-type">System</span>.exit(<span class="keyword">new</span> CommandLine(<span class="keyword">new</span> MayApp()).execute(args))
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Picocli 2.0 introduced special support for Groovy scripts. (From picocli 4.0 this was moved into a separate module, <code>picocli-groovy</code>.)</p>
</div>
<div class="paragraph">
<p>Scripts annotated with <code>@picocli.groovy.PicocliScript</code> are automatically transformed to use
<code>picocli.groovy.PicocliBaseScript</code> as their base class and can also use the <code>@Command</code> annotation to
customize parts of the usage message like command name, description, headers, footers etc.</p>
</div>
<div class="paragraph">
<p>Before the script body is executed, the <code>PicocliBaseScript</code> base class parses the command line and initializes
<code>@Field</code> variables annotated with <code>@Option</code> or <code>@Parameters</code>.
The script body is executed if the user input was valid and did not request usage help or version information.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="annotation">@Grab</span>(<span class="string"><span class="delimiter">'</span><span class="content">info.picocli:picocli-groovy:4.2.0</span><span class="delimiter">'</span></span>)
<span class="annotation">@Command</span>(name = <span class="string"><span class="delimiter">&quot;</span><span class="content">myScript</span><span class="delimiter">&quot;</span></span>,
        mixinStandardHelpOptions = <span class="predefined-constant">true</span>, <span class="comment">// add --help and --version options</span>
        description = <span class="string"><span class="delimiter">&quot;</span><span class="content">@|bold Groovy script|@ @|underline picocli|@ example</span><span class="delimiter">&quot;</span></span>)
<span class="annotation">@picocli</span>.groovy.PicocliScript
<span class="keyword">import</span> <span class="include">groovy.transform.Field</span>
<span class="keyword">import</span> <span class="include">static</span> <span class="include">picocli.CommandLine.*</span>

<span class="annotation">@Option</span>(names = [<span class="string"><span class="delimiter">&quot;</span><span class="content">-c</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">--count</span><span class="delimiter">&quot;</span></span>], description = <span class="string"><span class="delimiter">&quot;</span><span class="content">number of repetitions</span><span class="delimiter">&quot;</span></span>)
<span class="annotation">@Field</span> <span class="type">int</span> count = <span class="integer">1</span>;

<span class="comment">// PicocliBaseScript prints usage help or version if requested by the user</span>

count.times {
   println <span class="string"><span class="delimiter">&quot;</span><span class="content">hi</span><span class="delimiter">&quot;</span></span>
}
<span class="comment">// the CommandLine that parsed the args is available as a property</span>
<span class="keyword">assert</span> <span class="local-variable">this</span>.commandLine.commandName == <span class="string"><span class="delimiter">&quot;</span><span class="content">myScript</span><span class="delimiter">&quot;</span></span></code></pre>
</div>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
When upgrading scripts to picocli 4.0, just changing the version number is not enough!
Scripts should use <code>@Grab('info.picocli:picocli-groovy:4.2.0')</code>. The old artifact id <code>@Grab('info.picocli:picocli:4.2.0')</code> will not work,
because the <code>@picocli.groovy.PicocliScript</code> annotation class and supporting classes have been moved into a separate module, <code>picocli-groovy</code>.
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
When using a Groovy version older than 2.4.7, use this workaround for the <a href="https://issues.apache.org/jira/browse/GROOVY-7613">Grape bug</a> that causes this error:
<code>java.lang.ClassNotFoundException: # Licensed to the Apache Software Foundation (ASF) under one or more</code>.
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="groovy"><span class="annotation">@Grab</span>(<span class="string"><span class="delimiter">'</span><span class="content">info.picocli:picocli-groovy:4.2.0</span><span class="delimiter">'</span></span>)
<span class="annotation">@GrabExclude</span>(<span class="string"><span class="delimiter">'</span><span class="content">org.codehaus.groovy:groovy-all</span><span class="delimiter">'</span></span>) <span class="comment">// work around GROOVY-7613</span>
...</code></pre>
</div>
</div>
<div class="paragraph">
<p>In order to get you started quickly, you may have a look at the <a href="https://github.com/remkop/picocli/tree/master/picocli-examples/src/main/groovy/picocli/examples">Groovy examples</a> folder of the picocli code repository.</p>
</div>
</div>
<div class="sect2">
<h3 id="_kotlin">29.2. Kotlin</h3>
<div class="paragraph">
<p>Kotlin 1.2 (released Nov 28, 2017) officially supports <a href="http://kotlinlang.org/docs/reference/whatsnew12.html#array-literals-in-annotations">array literals in annotations</a>, allowing a more compact notation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="kotlin">@Command(name = &quot;MyApp&quot;, version = [&quot;Kotlin picocli v4.0 demo&quot;],
        mixinStandardHelpOptions = true, // add --help and --version options
        description = [&quot;@|bold Kotlin|@ @|underline picocli|@ example&quot;])
class MyApp : Callable&lt;Int&gt; {

    @Option(names = [&quot;-c&quot;, &quot;--count&quot;], paramLabel = &quot;COUNT&quot;,
            description = [&quot;the count&quot;])
    private var count: Int = 1

    override fun call(): Int {
        for (i in 0 until count) {
            println(&quot;hello world $i...&quot;)
        }
        return 0
    }
}
fun main(args: Array&lt;String&gt;) = System.exit(CommandLine(MyApp()).execute(*args))</code></pre>
</div>
</div>
<div class="paragraph">
<p>When specify a class as an argument of an annotation, use a Kotlin class (<a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.reflect/-k-class/index.html">KClass</a>).
The Kotlin compiler will automatically convert it to a Java class, so that the Java code will be able to see the annotations and arguments normally.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="kotlin">@Command(name = &quot;top&quot;, // ...
        subcommands = [SubCmd::class, picocli.CommandLine.HelpCommand::class])
class TopCmd { // ...
}

@Command(name = &quot;sub&quot;, /* ... */)
class SubCmd { // ...
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Kotlin versions prior to 1.2 did not allow the <a href="https://kotlinlang.org/docs/reference/annotations.html">array literal syntax in annotations</a>, so with older versions of Kotlin you will have to write <code>arrayOf(&#8230;&#8203;)</code> for the <code>names</code>, <code>description</code> and <code>type</code> attributes.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="kotlin">@Command(name = &quot;MyApp&quot;, version = arrayOf(&quot;picocli demo for Kotlin v1.0 and Kotlin v1.1&quot;),
        mixinStandardHelpOptions = true, // add --help and --version options
        description = arrayOf(&quot;@|bold Kotlin|@ @|underline picocli|@ example&quot;))
class MyApp : Callable&lt;Int&gt; {

    @Option(names = arrayOf(&quot;-c&quot;, &quot;--count&quot;),
            description = arrayOf(&quot;number of repetitions&quot;))
    private var count: Int = 1

    override fun call(): Int {
        for (i in 0 until count) {
            println(&quot;hello world $i...&quot;)
        }
        return 0
    }
}
fun main(args: Array&lt;String&gt;) = System.exit(CommandLine(MyApp()).execute(*args))</code></pre>
</div>
</div>
<div class="paragraph">
<p>In order to get you started quickly, you may have a look at the <a href="https://github.com/remkop/picocli/tree/master/picocli-examples/src/main/kotlin/picocli/examples/kotlin">Kotlin examples</a> folder of the picocli code repository.</p>
</div>
</div>
<div class="sect2">
<h3 id="_scala">29.3. Scala</h3>
<div class="paragraph">
<p>Scala does not allow specifying array annotation attribute as a single value,
so be aware that you will have to write <code>Array(&#8230;&#8203;)</code> for the <code>names</code>, <code>description</code> and <code>type</code> attributes.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="scala">@Command(name = &quot;MyApp&quot;, version = Array(&quot;Scala picocli demo v4.0&quot;),
         mixinStandardHelpOptions = true, // add --help and --version options
         description = Array(&quot;@|bold Scala|@ @|underline picocli|@ example&quot;))
class MyApp extends Callable[Int] {

    @Option(names = Array(&quot;-c&quot;, &quot;--count&quot;), paramLabel = &quot;COUNT&quot;,
            description = Array(&quot;the count&quot;))
    private var count: Int = 1

    def call() : Int = {
        for (i &lt;- 0 until count) {
            println(s&quot;hello world $i...&quot;)
        }
        0
    }
}
object MyApp {
    def main(args: Array[String]): Unit = {
        System.exit(new CommandLine(new MyApp()).execute(args: _*))
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>In order to get you started quickly, you may have a look at the <a href="https://github.com/remkop/picocli/tree/master/picocli-examples/src/main/scala/picocli/examples/scala">Scala examples</a> folder of the picocli code repository.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_api_javadoc">30. API Javadoc</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Picocli API Javadoc can be found <a href="apidocs/">here</a>.</p>
</div>
<div class="paragraph">
<p>See also: <a href="https://remkop.github.io/picocli/apidocs">latest version</a>, <a href="https://picocli.info/man/3.x/apidocs">picocli 3.x javadoc</a>.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_github_project">31. GitHub Project</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <a href="https://github.com/remkop/picocli">GitHub project</a> has the source code, tests, build scripts, etc.</p>
</div>
<div class="paragraph">
<p>Star <span class="icon"><i class="fa fa-star-o"></i></span> and/or fork <span class="icon"><i class="fa fa-code-fork"></i></span> this project on GitHub if you like it!</p>
</div>
<iframe src="https://ghbtns.com/github-btn.html?user=remkop&repo=picocli&type=star&count=true" frameborder="0" scrolling="0" width="170px" height="20px"></iframe>
<iframe src="https://ghbtns.com/github-btn.html?user=remkop&repo=picocli&type=fork&count=true" frameborder="0" scrolling="0" width="170px" height="20px"></iframe>
<iframe src="https://ghbtns.com/github-btn.html?user=remkop&type=follow&count=true" frameborder="0" scrolling="0" width="170px" height="20px"></iframe>
</div>
</div>
<div class="sect1">
<h2 id="_issue_tracker">32. Issue Tracker</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The GitHub <a href="https://github.com/remkop/picocli/issues">Issue Tracker</a> can be used to report bugs or request features. There is also a <a href="#_mailing_list">Mailing List</a>, and for questions where the user community may know the answer, <a href="https://stackoverflow.com/questions/tagged/picocli">StackOverflow</a> is both a good resource and a great way to build an online knowledge base.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_mailing_list">33. Mailing List</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Join the <a href="https://groups.google.com/d/forum/picocli">picocli Google group</a> if you are interested in discussing anything picocli-related and receiving announcements on new releases.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_license">34. License</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Picocli is licensed under the <a href="https://github.com/remkop/picocli/blob/master/LICENSE">Apache License 2.0</a>.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_releases">35. Releases</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Previous versions are available from the GitHub project <a href="https://github.com/remkop/picocli/releases">Releases</a>.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_download">36. Download</h2>
<div class="sectionbody">
<div class="paragraph">
<p>You can add picocli as an external dependency to your project, or you can include it as source.
See the <a href="#_source">source code</a> below. Copy and paste it into a file called <code>CommandLine.java</code>, add it to your project, and enjoy!</p>
</div>
<div class="sect2">
<h3 id="_gradle_3">36.1. Gradle</h3>
<div class="listingblock">
<div class="content">
<pre>compile 'info.picocli:picocli:4.2.0'</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_maven_3">36.2. Maven</h3>
<div class="listingblock">
<div class="content">
<pre>&lt;dependency&gt;
  &lt;groupId&gt;info.picocli&lt;/groupId&gt;
  &lt;artifactId&gt;picocli&lt;/artifactId&gt;
  &lt;version&gt;4.2.0&lt;/version&gt;
&lt;/dependency&gt;</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_scala_sbt">36.3. Scala SBT</h3>
<div class="listingblock">
<div class="content">
<pre>libraryDependencies += "info.picocli" % "picocli" % "4.2.0"</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_ivy">36.4. Ivy</h3>
<div class="listingblock">
<div class="content">
<pre>&lt;dependency org="info.picocli" name="picocli" rev="4.2.0" /&gt;</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_source">36.5. Source</h3>
<div class="paragraph">
<p>Picocli has only one source file: <a href="https://github.com/remkop/picocli/blob/master/src/main/java/picocli/CommandLine.java">CommandLine.java</a>.
This facilitates including it in your project in source form to avoid having an external dependency on picocli.</p>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Version 4.2.0<br>
Last updated 2020-04-02 12:14:30 +0900
</div>
</div>
</body>
</html>